Skip to main content
This guide covers everything you need to install and configure the Shopify Subscriptions Reference App.

​
Prerequisites

Before you begin, ensure you have the following installed and configured:

​
Required Software

Node.js

Version 18 or higher requiredDownload from nodejs.org

Shopify CLI

Version 3.81 or higherInstall with:
npm install -g @shopify/cli

Git

For cloning the repositoryDownload from git-scm.com

Package Manager

npm, yarn, or pnpmChoose your preferred package manager

​
Shopify Requirements

You’ll need:
Make sure your development store has checkout enabled. Subscription apps require the full checkout flow to function properly.

​
Installation Methods

Choose one of the following methods to install the app: The fastest way to get started is using the Shopify CLI template: 
shopify app init --template https://github.com/Shopify/subscriptions-reference-app
This command will:
  1. Clone the repository to a new directory
  2. Prompt you for a project name
  3. Install all dependencies automatically
  4. Set up the initial configuration

​
Method 2: Manual Clone

Alternatively, clone the repository directly: 
git clone https://github.com/Shopify/subscriptions-reference-app.git
cd subscriptions-reference-app
Then install dependencies with your preferred package manager: 
npm install

​
Database Setup

The app uses Prisma as its ORM with SQLite for local development.

​
Database Schema

The app includes three main database models:
Manages OAuth sessions and tokens for the Shopify Admin API:
  • Shop domain and access tokens
  • User information
  • Session expiration
  • Online/offline session types
Controls when subscription billing attempts occur:
  • Shop-specific billing hours
  • Timezone configuration
  • Active/inactive status
Manages dunning (failed payment retry) workflows:
  • Contract ID and billing cycle
  • Failure reasons
  • Completion status and timestamps

​
Initialize the Database

Run the setup command to generate the Prisma client and apply migrations: 
npm run setup
This runs: 
prisma generate    # Generates type-safe Prisma Client
prisma migrate deploy   # Applies database migrations
The database file will be created at prisma/data.db.
For production deployments, you’ll want to use a production-grade database like PostgreSQL. Update the datasource in prisma/schema.prisma:
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

​
Environment Configuration

The app uses environment variables for configuration. The Shopify CLI manages most of these automatically during development.

​
Development Environment

When you run npm run dev, the Shopify CLI will:
  • Generate a tunnel URL for local development
  • Set up OAuth credentials
  • Configure the SHOPIFY_APP_URL automatically

​
Key Environment Variables

# Automatically managed by Shopify CLI
SHOPIFY_API_KEY=your-api-key
SHOPIFY_API_SECRET=your-api-secret
SHOPIFY_APP_URL=https://your-tunnel.ngrok.io
SCOPES=read_products,write_products,...

# Database (local development)
DATABASE_URL=file:./data.db

# Server configuration
PORT=3000
NODE_ENV=development
Never commit environment files (.env, .env.production) to version control. These contain sensitive credentials.

​
App Scopes Configuration

The app requires specific Shopify API scopes defined in shopify.app.toml.

​
Required Scopes

The following scopes are configured in the app:
shopify.app.toml
[access_scopes]
scopes = "customer_read_customers,customer_read_orders,customer_read_own_subscription_contracts,customer_write_customers,customer_write_own_subscription_contracts,read_all_orders,read_locales,read_locations,read_themes,write_customer_payment_methods,write_customers,write_metaobject_definitions,write_metaobjects,write_orders,write_own_subscription_contracts,write_products,write_translations,read_analytics"

​
Scope Breakdown

  • customer_read_customers - Read customer information
  • customer_write_customers - Update customer details
  • customer_read_orders - View customer order history
  • customer_read_own_subscription_contracts - Read subscription contracts
  • customer_write_own_subscription_contracts - Manage customer subscriptions
  • write_customer_payment_methods - Manage customer payment methods for subscriptions
  • write_products - Create and update products with selling plans
  • read_all_orders - Access order data for billing
  • write_orders - Create subscription renewal orders
  • write_own_subscription_contracts - Full subscription contract management
  • Core scope for subscription apps
  • write_metaobject_definitions - Define custom metaobjects
  • write_metaobjects - Store subscription-related metadata
  • read_locales / write_translations - Multi-language support
  • read_themes - Theme integration
  • read_analytics - Access subscription analytics and reporting

​
Updating Scopes

If you need to add or modify scopes:
  1. Update the scopes line in shopify.app.toml
  2. Stop the development server
  3. Run npm run dev again
  4. Reinstall the app when prompted
The app will automatically request the new scopes during reinstallation.

​
Webhook Configuration

The app listens for various subscription-related webhooks configured in shopify.app.toml:

​
Subscription Contract Webhooks

[[webhooks.subscriptions]]
topics = [ "subscription_contracts/create" ]
uri = "/webhooks/subscription_contracts/create"

[[webhooks.subscriptions]]
topics = [ "subscription_contracts/activate" ]
uri = "/webhooks/subscription_contracts/activate"

[[webhooks.subscriptions]]
topics = [ "subscription_contracts/cancel" ]
uri = "/webhooks/subscription_contracts/cancel"

[[webhooks.subscriptions]]
topics = [ "subscription_contracts/pause" ]
uri = "/webhooks/subscription_contracts/pause"

​
Billing Webhooks

[[webhooks.subscriptions]]
topics = [ "subscription_billing_attempts/success" ]
uri = "/webhooks/subscription_billing_attempts/success"

[[webhooks.subscriptions]]
topics = [ "subscription_billing_attempts/failure" ]
uri = "/webhooks/subscription_billing_attempts/failure"

[[webhooks.subscriptions]]
topics = [ "subscription_billing_cycles/skip" ]
uri = "/webhooks/subscription_billing_cycles/skip"

​
Selling Plan Webhooks

[[webhooks.subscriptions]]
topics = [ "selling_plan_groups/create", "selling_plan_groups/update" ]
uri = "/webhooks/selling_plan_groups/create_or_update"
Webhooks are automatically registered when you install the app. The Shopify CLI manages webhook registration during development.

​
Running the App

​
Start Development Server

Launch the app in development mode: 
npm run dev
This command:
  • Starts the Remix dev server
  • Opens a secure tunnel for webhooks
  • Watches for file changes and hot reloads
  • Opens your browser to the app installation URL

​
Available Scripts

# Start dev server with Shopify CLI
npm run dev

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

​
Verify Installation

After installation, verify everything is working:
1

Check the app loads

Navigate to your development store admin and open the app. You should see the subscription contracts dashboard.
2

Verify database connection

The app should load without errors. Check the terminal for any database connection issues.
3

Test GraphQL connection

Visit the GraphiQL endpoint shown in your terminal output (e.g., https://your-tunnel.ngrok.io/graphiql) to test API queries.
4

Create a test plan

Try creating a selling plan from the app interface to ensure write operations work correctly.

​
Next Steps

Quickstart Guide

Follow the quickstart to create your first subscription

Setup & Configuration

Learn about advanced configuration options

Core Concepts

Understand subscription contracts and selling plans

Deployment

Deploy your app to production

​
Troubleshooting

Install the Shopify CLI globally:
npm install -g @shopify/cli@latest
Verify installation:
shopify version
Reset and regenerate the database:
rm -f prisma/data.db
npm run setup
This deletes the existing database and recreates it with fresh migrations.
Clear node modules and reinstall:
rm -rf node_modules package-lock.json
npm install
For pnpm users:
rm -rf node_modules pnpm-lock.yaml
pnpm install
The default port is 3000. If it’s in use, set a different port:
PORT=3001 npm run dev
Or update the port in vite.config.ts.
The Shopify CLI uses ngrok for tunneling. If you have connection issues:
  1. Check your firewall settings
  2. Try restarting the dev server
  3. Ensure ngrok isn’t blocked by your network
Alternatively, use a custom tunnel with:
shopify app dev --tunnel-url https://your-custom-url.com
For deployment to production environments, see the Deployment Guide for platform-specific instructions and best practices.

Build docs developers (and LLMs) love

Get started for freeTalk to us