All Tutorials

Add billing to your Shopify app

All Tutorials

Add billing to your Shopify app

On this page

Add billing to your Shopify 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:

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.

Requirements

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, 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 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.

If the charge is declined, then Shopify automatically redirects the user back to Apps page in the Shopify admin. A message displays on the Apps page to let the user know that they declined the charge. If the charge is accepted, then Shopify automatically redirects the user to the return_url specified in the request.

Step 2: Activate the charge

When Shopify redirects the user to the return_url, you can then activate the charge.

get '/activatecharge' do
  recurring_application_charge = ShopifyAPI::RecurringApplicationCharge.find(request.params['charge_id'])
  recurring_application_charge.status == "accepted" ? recurring_application_charge.activate : redirect(bulk_edit_url)

  create_order_webhook
  redirect bulk_edit_url
end

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.

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.

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.

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

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 create_usage_charge

If you're interested in learning more about Shopify’s Billing API, see our Charging for your app documentation.