Adding billing to your app
The following tutorial describes how to use Shopify's Billing API to programmatically charge users of your app.
Shopify's Billing API has three API endpoints available to manage billing of your app:
- ApplicationCharge is used to bill your users one time only.
- RecurringApplicationCharge is used to bill your users on a recurring 30-day billing cycle.
- UsageCharge is used to bill your users when the fees are recurring, but vary from month to month.
For this tutorial, you will use the RecurringApplicationCharge endpoint to charge your users a $9.99 recurring monthly fee with a 7 day trial period. Additionally, you will use the UsageCharge endpoint to charge a variable monthly fee of $0.99 for every new Gift Basket order created on the users shop.
The sample code for this tutorial builds on the Building a public Shopify application tutorial and can be found in this GitHub repository. When working on this tutorial, make sure to add your
APP_URL to the app.rb file. Also, 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.
- Completion of the Building a public Shopify application tutorial
Step 1: Create a recurring charge
To create a recurring monthly charge of $9.99, create a method named
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, 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 the user is redirected to once they accept/decline the charge.
- trial_days - Number of days that the user is eligible for a free trial.
- test - Indicates if the charge is a test transaction. Valid values are "true" or "null". If "true", the users credit card will not be charged.
- capped_amount - The limit a customer can be charged for usage based billing.
- terms - States the terms and conditions of usage based billing charges.
After the RecurringApplicationCharge is created, it is held in a pending state until the user accepts or declines the charge. As a result, you will need to redirect the user to the
confirmation_url given in the response where they will be prompted to accept or decline the charge.
After the charge has been accepted or declined, Shopify automatically redirects the user to the
return_url specified in the request. At this point, the RecurringApplicationCharge is either in an accepted or declined state; however, to receive payment, you will need to activate the RecurringApplicationCharge.
Step 2: Activate the charge
When Shopify redirects the user to the
return_url, you can then activate the charge.
To successfully activate the charge, use the
charge_id from the Shopify redirect request to find the correct RecurringApplicationCharge. Check the status of the RecurringApplicationCharge and activate the charge using the
activate method from the Shopify API gem.
You have now successfully created and activated a RecurringApplicationCharge that will automatically bill your users monthly.
Step 3: Create a usage charge
To charge your users $0.99 for every new Gift Basket order created on their shop, you will need to create a new UsageCharge for each new order. Start by creating a method named
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
Now that you have a method in place to create a $0.99 variable charge for every new Gift Basket order created, your app will need a way to be notified of new orders. For this, you can use the Shopify API to register an 'order/create' webhook.
Now, whenever a new order is created on the users shop, an 'order/create' webhook will send 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
If you're interested in learning more about Shopify’s Billing API, see our Charging for your app documentation.