Shopify Billing API

The billing API lets you issue charges to users of your application. These charges can be either recurring (on a monthly billing cycle) or on a one-time basis, so setting up free trials, discount codes, comped subscriptions, and upgrading/downgrading plans is all possible and easily done.

Once issued a charge, you then redirect the user to a confirmation page. After accepting the charge, your application must activate it. At this point, Shopify adds the application charge to the shop’s regular invoice to be paid as usual.

80% of the charged amount is paid out to you as a Partner once the shop owner pays Shopify.

Note that test/demo shops may not be charged.

One time charges

Creating

Using the Shopify App plugin based on ActiveResource, one-time charges are created like this:

charge = ShopifyAPI::ApplicationCharge.create(:name => 'Usage fee for a cool app',
                                              :price => 4.99,
                                              :return_url => 'http://yourapp.com/charges/confirm')

redirect_to charge.confirmation_url

The charge’s confirmation_url is to a page on which the application user can accept your charge.

After the charge is accepted or declined, Shopify redirects the user to the return_url and appends a parameter charge_id, which your application must use to activate the charge, a necessary step in order to get paid through the API.

An example url Shopify would redirect to is http://yourapp.com/charges/confirm?charge_id_=12345

Typical one-time charge code looks something like this:

class ApplicationController < ActionController::Base
  before_filter :charge_merchant              

  # ...

  def charge_merchant
    unless merchant_has_paid?
      charge = ShopifyAPI::ApplicationCharge.create(:name => "Usage fee for a cool app", 
                                                    :price => 4.99, 
                                                    :return_url => "http://yourapp.com/charges/confirm")

      redirect_to charge.confirmation_url
    end
  end
end

class ChargesController < ApplicationController
  around_filter :shopify_session
  
  def confirm
    # the old method of checking for params[:accepted] is deprecated.
    ShopifyAPI::ApplicationCharge.find(params[:charge_id]).activate

    # update local data store
  end
end

Testing

When creating an ApplicationCharge, if the test attribute is set to true, Shopify will not charge credit cards when the shop’s invoice has been paid.

ShopifyAPI::ApplicationCharge.create(:name => 'Usage fee for a cool app', 
                                     :price => 4.99, 
                                     :return_url => 'http://yourapp.com/charges/confirm',
                                     :test => true)

All other behaviour is unchanged – the charge must still be accepted by a user, your application must activate the charge, and emails are still sent out.

Recurring Charges

Creating

Using the Shopify App plugin based on ActiveResource, recurring charges are created like this:

charge = ShopifyAPI::RecurringApplicationCharge.create(:name => 'Basic plan',
                                                       :price => 4.99,
                                                       :return_url => 'http://yourapp.com/charges/confirm')
redirect_to charge.confirmation_url

Confirmation, subsequent redirection, and activation works the same as it does for one-time charges.

Note that a shop may have only one active recurring charge per application at a time. See Updating.

Typical recurring charge code looks like this:

class ApplicationController < ActionController::Base
  before_filter :ensure_merchant_has_paid

  # ...

  def ensure_merchant_has_paid
    unless ShopifyAPI::RecurringApplicationCharge.current
      charge = ShopifyAPI::RecurringApplicationCharge.create(:name => "Basic plan", 
                                                             :price => 4.99)
      redirect_to charge.confirmation_url
    end
  end
end

class ChargesController < ApplicationController
  around_filter :shopify_session
  
  def confirm
    # the old method of checking for params[:accepted] is deprecated.
    ShopifyAPI::RecurringApplicationCharge.find(params[:charge_id]).activate

    # update local data store
  end
end

Accessing

Access a shop’s current RecurringApplicationCharge by calling

current_plan = ShopifyAPI::RecurringApplicationCharge.current

Access all recurring charges ever issued to a shop (including those previously cancelled) by calling

all_plans_ever_created = ShopifyAPI::RecurringApplicationCharge.find_all

Updating

Each shop may have only one recurring charge per application.

When a new RecurringApplicationCharge is activated for a shop that already has a recurring charge for that application, the existing recurring charge will be cancelled and pro-rated for the duration it has been active for. The new recurring charge will then activate.

This means that upgrading and downgrading a user’s recurring charge or plan is straightforward; just change their plan, have them accept, and Shopify takes care of the rest.

Cancelling

Cancel a subscription by calling

current_plan = ShopifyAPI::RecurringApplicationCharge.current
current_plan.cancel

Cancelled plans are not pro-rated. The shop will be charged for the full month-long billing cycle.

Testing

When creating a RecurringApplicationCharge, if the test attribute is set to true, Shopify will not charge credit cards when the shop’s invoice has been paid.

ShopifyAPI::RecurringApplicationCharge.create(:name => 'Usage fee for a cool app', 
                                              :price => 4.99, 
                                              :return_url => 'http://yourapp.com/charges/confirm',
                                              :test => true)

Shopify © 2012