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:

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

Requirements

• 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 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/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.

The capped_amount and terms parameters must be present in order to create a UsageCharge. These two fields are presented to the merchant when they approve the usage charges for your app.

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.

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.

The trial period will go into effect at the time the RecurringApplicationCharge is activated.

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 your app only needs to utilize the UsageCharge endpoint, you will still need to create a parent RecurringApplicationCharge with price set to 0.

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