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 the app.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 or null. If true, 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 from pending to active.

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.