Creating a Billable App

Introduction

First of all, its best to read up on Shopify's documentation to get to know how it works internally.

To enable billing on your app, there is configuration already in config/shopify-app.php which is based on environment variables. Using these variables, here is what you need to setup.

• Options
• Flow
• Grandfather Mode
• Model Methods
• Upgrading-or-Downgrading Plans

Options / Setup

Here is an example setup to get a basic app into billable mode:

SHOPIFY_BILLING_ENABLED=1
SHOPIFY_BILLING_TYPE=recurring
SHOPIFY_BILLING_PLAN="Demo Plan"
SHOPIFY_BILLING_TEST=1
SHOPIFY_BILLING_PRICE=15.00
SHOPIFY_BILLING_TRIAL_DAYS=14

Here is an explanation of the configuration, many are already set with sane-defaults:

billing_enabled (required)

SHOPIFY_BILLING_ENABLED=0 to disable billing state for application (default)

SHOPIFY_BILLING_ENABLED=1 to enable billing state for application

billing_type (required)

SHOPIFY_BILLING_TYPE=recurring for recurring monthly billing (default)

SHOPIFY_BILLING_TYPE=single for a one-time charge

billing_plan (optional)

SHOPIFY_BILLING_PLAN="Your plan name" for a plan name to display to the customer

billing_price (required)

SHOPIFY_BILLING_PRICE=0.00 for a price of the plan

billing_trial_days (optional)

SHOPIFY_BILLING_TRIAL_DAYS=0 for number of days for trial (default: 7)

billing_test (optional)

SHOPIFY_BILLING_TEST=0 to disable testing mode (default)

SHOPIFY_BILLING_TEST=1 to enable testing mode

billing_redirect (required)

SHOPIFY_BILLING_REDIRECT="/url/path" for setting the path to handle the accepting or declining of the application charge (default: /billing/proccess)

Note: Its not recommended to change this unless you're using custom logic or overriding the billing controller.

Flow

Once you've set the required environment variables, you're ready to go.

Here's how the flow works:

1. Shop installs the app
2. Shop accepts the app's permissions
3. Shop is presented with the billing screen to accept or decline
   • 3a. If they accept, charge is activated, charge ID is saved to database, shop is sent to your app's homepage
   • 3b. If they decline, charge is marked declined, shop is sent to error screen saying they did not pay.

Note: If billing is being applied on top of an existing app, when the shop accesses your app, they will sent to the billing screen.

Grandfather Mode

Grandfather mode is useful when you wish to give a shop free access to your app. A simple boolean flag in the database (grandfathered) tells the billable middleware to let them through.

Setting via Database

UPDATE shops SET grandfathered = 1 WHERE shopify_domain = "domain.myshopify.com"

Setting via PHP

// Lookup
$shop = Shop::where('shopify_domain', 'domain.myshopify.com')->first();

// Or, for a current shop logged in
$shop = ShopifyApp::shop();

$shop->grandfathered = 1;
$shop->save();

Model Methods

isPaid()

$shop->isPaid() will return true or false if a shop has a charge_id in the database.

Also accessible: $shop->charge_id to get the raw charge ID.

isGrandfathered()

$shop->isGrandfathered() will return true or false if a shop is grandfathered in.

Upgrading or Downgrading Plans

Shopify internally handles cancelling the previous plan. You simply need to direct the shop to the billing screen to accept the new charge.

Programmatically, you can do this with the package's BillingPlan class.