Add billing to your Shopify app
The REST Admin API provides an integrated billing solution that allows app charges to be handled by Shopify's merchant invoicing system. This guide illustrates how to programmatically charge merchants that are using your app.
The sample code referenced in this tutorial is available in the Shopify/example-ruby-app GitHub repository.
API resources
The following REST Admin API resources are available to help you meet the needs of your specific billing model:
- ApplicationCharge: Used to bill merchants one time only (for example, when their free trial expires). This type of charge is recommended for apps that aren’t billed on a recurring basis.
- RecurringApplicationCharge: Used to bill merchants on a recurring 30-day billing cycle.
- UsageCharge: Used to charge merchants when fees are recurring, but vary from month to month.
What you'll build
In this tutorial, you'll use the RecurringApplicationCharge
endpoint to charge merchants a $9.99 recurring monthly fee with a 7-day trial period.
You'll also use the UsageCharge
endpoint to charge a variable monthly fee of $0.99 for every new gift basket order created on the merchant's shop.
Requirements
You need to complete the Building a public Shopify application tutorial.
When working through this tutorial, make sure to do the following:
- Add your
APP_URL
to theapp.rb
file. - Include a
.env
file inside the current app directory that includes your API key and secret. - Run your app (
ruby app.rb
) from within the "02 Charging For Your App" folder.
Step 1: Create a recurring charge
To create a recurring monthly charge of $9.99, create a method named create_recurring_application_charge
:
def create_recurring_application_charge
unless ShopifyAPI::RecurringApplicationCharge.current
recurring_application_charge = ShopifyAPI::RecurringApplicationCharge.new(
name: "Gift Basket Plan",
price: 9.99,
return_url: "https:\/\/#{APP_URL}\/activatecharge",
test: true,
trial_days: 7,
capped_amount: 100,
terms: "$0.99 for every order created")
if recurring_application_charge.save
@tokens[:confirmation_url] = recurring_application_charge.confirmation_url
redirect recurring_application_charge.confirmation_url
end
end
end
This method checks to see if there is already an existing and activated RecurringApplicationCharge
using the current
method from the Shopify API gem. If there is no existing and activated charge, then it issues a request to the Shopify API to create a new RecurringApplicationCharge
with the following parameters:
- name - The name of the
RecurringApplicationCharge
. This name appears on the shop owner’s invoice. - price - The price of the
RecurringApplicationCharge
. - return_url - The URL that the merchant is redirected to when they accept the charge.
- test - Indicates if the charge is a test transaction. Valid values are
true
ornull
. Iftrue
, then the merchant's credit card won't be charged. - trial_days - The number of days that the merchant is eligible for a free trial.
- capped_amount - The limit a merchant can be charged for usage based billing.
- terms - The terms and conditions of usage based billing charges.
Step 2: Receive confirmation
After the RecurringApplicationCharge
is created, it's held in a pending
state until the merchant accepts or declines the charge. As a result, you'll need to redirect the merchant to the confirmation_url
given in the response where they'll be prompted to accept or decline the charge.

- If the charge is declined, then Shopify automatically redirects the merchant back to Apps page in the Shopify admin. A message displays on the Apps page to let the merchant know that they declined the charge.
- If the charge is accepted, then Shopify automatically redirects the merchant to the
return_url
specified in the request. As of API version 2021-01, when a merchant accepts a charge, the charge immediately transitions frompending
toactive
.
Step 3: Create a usage charge
To charge merchants $0.99 for every new gift basket order created on their shop, you'll need to create a new UsageCharge
for each new order. Start by creating a method named create_usage_charge
:
post '/giftbasket/webhook/order_create' do
...
create_usage_charge
...
end
def create_usage_charge
usage_charge = ShopifyAPI::UsageCharge.new(description: "$0.99 for every order created", price: 0.99)
recurring_application_charge = ShopifyAPI::RecurringApplicationCharge.current
usage_charge.prefix_options = {recurring_application_charge_id: recurring_application_charge.id}
usage_charge.save
end
The create_usage_charge
method makes a request to the Shopify API to create a UsageCharge
with the following parameters:
- description - The name of the usage charge.
- price - The price of the usage charge.
A UsageCharge
belongs to your current RecurringApplicationCharge
and the Shopify API gem provides a prefix_options
method to assign a UsageCharge
to the RecurringApplicationCharge
.
Step 4: Get notified about new orders
Now that you have a method in place to create a $0.99 variable charge for every new gift basket order created, your app needs a way to be notified of new orders. For this, you can use the Shopify API to register an order/create
webhook.
def create_order_webhook
unless ShopifyAPI::Webhook.find(:all).any?
webhook = {
topic: 'orders/create',
address: "https:\/\/#{APP_URL}\/giftbasket\/webhook\/order_create",
format: 'json'}
ShopifyAPI::Webhook.create(webhook)
end
end
Whenever a new order is created on the merchant's shop, an order/create
webhook sends a POST request to the webhook address you have defined in the register_order_webhook
method. Your app can then use the POST request to invoke the create_usage_charge
.
More information
To learn more about REST Admin API resources for billing, refer to our Charging for your app with the REST Admin API guide.