Skip to main content
This guide walks you through the complete setup process for the Shopify Subscriptions Reference App, from installation to running your first development server.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18+ installed
  • A Shopify Partner account
  • A development store
  • pnpm, npm, or yarn package manager

​
Installation

1

Install the app using Shopify CLI

The easiest way to get started is using the Shopify CLI:
shopify app init --template https://github.com/Shopify/subscriptions-reference-app
This clones the repository and sets up the basic structure.
2

Install dependencies

Navigate to your app directory and install dependencies:
pnpm install
Or with npm:
npm install
3

Set up the database

The app uses Prisma with SQLite by default. Generate the Prisma client and run migrations:
pnpm setup
This runs:
  • prisma generate - Generates the Prisma client
  • prisma migrate deploy - Runs database migrations

​
Database Configuration

The app uses Prisma ORM with SQLite for local development. The database schema is defined in prisma/schema.prisma.

​
Database Schema

datasource db {
  provider = "sqlite"
  url      = "file:./data.db"
}

model Session {
  id            String    @id
  shop          String
  state         String
  isOnline      Boolean   @default(false)
  scope         String?
  expires       DateTime?
  accessToken   String
  userId        BigInt?
  firstName     String?
  lastName      String?
  email         String?
  accountOwner  Boolean   @default(false)
  locale        String?
  collaborator  Boolean?  @default(false)
  emailVerified Boolean?  @default(false)
}

model BillingSchedule {
  id        Int      @id @default(autoincrement())
  shop      String   @unique
  hour      Int      @default(10)
  timezone  String   @default("America/Toronto")
  active    Boolean  @default(true)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model DunningTracker {
  id                Int       @id @default(autoincrement())
  shop              String
  contractId        String
  billingCycleIndex Int
  failureReason     String
  completedAt       DateTime?
  completedReason   String?

  @@unique([shop, contractId, billingCycleIndex, failureReason])
  @@index([completedAt])
}

​
Running Migrations

When you make changes to the schema: 
pnpm prisma migrate dev --name your_migration_name
For production deployments: 
pnpm db:migrate

​
Shopify App Configuration

The app configuration is managed in shopify.app.toml.

​
App Settings

name = "Subscriptions application"
client_id = "subscriptions-app-key"
application_url = "https://example.com"
embedded = true

[build]
automatically_update_urls_on_dev = true

​
Required Scopes

The app requires the following access scopes: 
[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"
These scopes are required for full subscription management functionality including:
  • Managing subscription contracts
  • Updating customer payment methods
  • Creating and modifying orders
  • Managing selling plans

​
OAuth Redirect URLs

[auth]
redirect_urls = [
  "https://example.com/auth/callback",
  "https://example.com/auth/shopify/callback",
  "https://example.com/api/auth/callback",
]

​
Environment Variables

While the app doesn’t include a .env.example file, the following environment variables are managed by the Shopify CLI during development:

​
Core Variables

VariableDescriptionSet By
SHOPIFY_API_KEYYour app’s API keyShopify CLI
SHOPIFY_API_SECRETYour app’s API secretShopify CLI
SHOPIFY_APP_URLYour app’s URLShopify CLI
SCOPESOAuth scopes from shopify.app.tomlShopify CLI

​
Database Variables

VariableDescriptionDefault
DATABASE_URLPrisma database connection stringfile:./data.db
Never commit your .env file to version control. The .gitignore file is pre-configured to exclude environment files.

​
Running the Development Server

1

Start the dev server

Use the Shopify CLI to start the development server:
pnpm dev
This command:
  • Starts the Remix development server
  • Opens a tunnel to your local server
  • Updates your app URLs automatically
  • Provides a preview URL for testing
2

Install the app on your development store

The CLI will provide a URL to install the app on your store. Click the link and follow the OAuth flow.
3

Verify the installation

Once installed, you should see the app in your Shopify admin under Apps.

​
Production Configuration

For production deployments, you’ll need to:
  1. Set up a production database - Consider using PostgreSQL or MySQL instead of SQLite
  2. Configure environment variables on your hosting platform
  3. Update the database provider in prisma/schema.prisma
  4. Run migrations using pnpm db:migrate
  5. Build the app using pnpm build

​
Example PostgreSQL Configuration

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

​
Webhook Configuration

Webhooks are automatically configured through shopify.app.toml. See the Handling Webhooks guide for implementation details.

​
Testing the Setup

Verify your setup is working: 
# Run type checking
pnpm type-check

# Run tests
pnpm test

# Run linting
pnpm lint

​
Troubleshooting

​
Database Connection Issues

If you encounter database errors: 
# Reset the database
rm prisma/data.db
pnpm setup

​
OAuth Errors

If OAuth fails:
  1. Verify your shopify.app.toml configuration
  2. Check that your app URL matches the CLI tunnel URL
  3. Ensure all required scopes are listed

​
Build Errors

For build issues: 
# Clear node modules and reinstall
rm -rf node_modules
pnpm install

​
Next Steps

Creating Selling Plans

Learn how to create and manage subscription selling plans

Managing Subscriptions

Manage subscription contracts and customer subscriptions

Build docs developers (and LLMs) love

Get started for freeTalk to us