Skip to main content
Get your subscription app up and running quickly with this step-by-step guide. You’ll go from installation to creating your first subscription plan.
1

Create a new app using Shopify CLI

The fastest way to get started is using the Shopify CLI with the template:
shopify app init --template https://github.com/Shopify/subscriptions-reference-app
This command will:
  • Clone the repository
  • Install all dependencies automatically
  • Set up the project structure
Make sure you have Shopify CLI installed before running this command.
2

Install dependencies

If you cloned the repository manually, install dependencies using your preferred package manager:
npm install
The app uses Node.js and includes dependencies like:
  • Remix for the web framework
  • Prisma for database management
  • Shopify App Bridge and Polaris for UI
3

Set up the database

Initialize the database with Prisma:
npm run setup
This command runs:
  • prisma generate - Generates the Prisma Client
  • prisma migrate deploy - Applies database migrations
The app uses SQLite by default for local development. The database file will be created at prisma/data.db.
4

Start the development server

Launch the app with the Shopify CLI:
npm run dev
This will:
  • Start the Remix development server
  • Open a tunnel for local development
  • Launch your browser with the app installation URL
The first time you run the app, you’ll be prompted to log in to your Shopify Partner account and select a development store.
Expected output:
╭─ info ────────────────────────────────────────────────────────────────────╮
│                                                                            │
│  Using development store: your-store.myshopify.com                        │
│                                                                            │
│  Preview URL: https://your-store.myshopify.com/admin/apps/...             │
│                                                                            │
│  GraphiQL URL: https://your-tunnel-url.ngrok.io/graphiql                  │
│                                                                            │
╰────────────────────────────────────────────────────────────────────────────╯
5

Install the app on your development store

  1. Click the Preview URL from the terminal output
  2. Click Install app in your Shopify admin
  3. Review and approve the required permissions
The app will request the following scopes:
  • Customer read/write permissions
  • Order read/write permissions
  • Subscription contract management
  • Payment method management
  • Product and metaobject access
See the installation guide for detailed scope information.
6

Create your first subscription plan

Now that the app is installed, create a selling plan:
  1. In the app, navigate to Plans from the main navigation
  2. Click Create plan
  3. Fill in the plan details:
    • Plan name (e.g., “Monthly Coffee Subscription”)
    • Billing frequency (e.g., every 1 month)
    • Delivery frequency
  4. Select products to include in the plan
  5. Click Save

Understanding Selling Plans

Learn more about how selling plans work in Shopify’s subscription system
7

Test subscription checkout

To test the subscription flow:
  1. Go to your online store
  2. Add a product with a subscription plan to your cart
  3. Select the subscription option at checkout
  4. Complete a test purchase using Shopify’s test payment methods
The subscription contract will appear in the app’s Contracts page.

​
Next steps

Now that you have the app running, explore these features:

Installation Details

Learn about prerequisites, environment variables, and configuration options

Managing Contracts

Understand how subscription contracts work

Billing & Payments

Configure billing schedules and handle payment failures

Extensions

Extend the app with custom UI and functionality

​
Troubleshooting

Make sure you’ve run the setup command:
npm run setup
This generates the Prisma client and creates the database file.
If you see a missing scopes error, you need to update the app scopes:
  1. Stop the development server
  2. Run npm run dev again
  3. Reinstall the app when prompted
The app will automatically request any new scopes defined in shopify.app.toml.
Regenerate the GraphQL types:
npm run graphql-codegen
This updates type definitions from Shopify’s Admin API schema.
For more detailed setup instructions and advanced configuration, see the Installation Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us