> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Shopify/subscriptions-reference-app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get the Shopify Subscriptions Reference App running in minutes

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.

<Steps>
  <Step title="Create a new app using Shopify CLI">
    The fastest way to get started is using the Shopify CLI with the template:

    ```bash theme={null}
    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

    <Note>
      Make sure you have [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) installed before running this command.
    </Note>
  </Step>

  <Step title="Install dependencies">
    If you cloned the repository manually, install dependencies using your preferred package manager:

    <CodeGroup>
      ```bash npm theme={null}
      npm install
      ```

      ```bash yarn theme={null}
      yarn install
      ```

      ```bash pnpm theme={null}
      pnpm install
      ```
    </CodeGroup>

    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
  </Step>

  <Step title="Set up the database">
    Initialize the database with Prisma:

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Start the development server">
    Launch the app with the Shopify CLI:

    ```bash theme={null}
    npm run dev
    ```

    This will:

    * Start the Remix development server
    * Open a tunnel for local development
    * Launch your browser with the app installation URL

    <Warning>
      The first time you run the app, you'll be prompted to log in to your Shopify Partner account and select a development store.
    </Warning>

    Expected output:

    ```bash theme={null}
    ╭─ 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                  │
    │                                                                            │
    ╰────────────────────────────────────────────────────────────────────────────╯
    ```
  </Step>

  <Step title="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](/installation) for detailed scope information.
  </Step>

  <Step title="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**

    <Card title="Understanding Selling Plans" icon="calendar" href="/concepts/selling-plans">
      Learn more about how selling plans work in Shopify's subscription system
    </Card>
  </Step>

  <Step title="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](https://shopify.dev/docs/apps/build/checkout/test-purchases)

    The subscription contract will appear in the app's **Contracts** page.
  </Step>
</Steps>

## Next steps

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

<CardGroup cols={2}>
  <Card title="Installation Details" icon="gear" href="/installation">
    Learn about prerequisites, environment variables, and configuration options
  </Card>

  <Card title="Managing Contracts" icon="file-contract" href="/concepts/subscription-contracts">
    Understand how subscription contracts work
  </Card>

  <Card title="Billing & Payments" icon="credit-card" href="/concepts/billing-cycles">
    Configure billing schedules and handle payment failures
  </Card>

  <Card title="Extensions" icon="puzzle-piece" href="/extensions/overview">
    Extend the app with custom UI and functionality
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="App won't start - database connection error">
    Make sure you've run the setup command:

    ```bash theme={null}
    npm run setup
    ```

    This generates the Prisma client and creates the database file.
  </Accordion>

  <Accordion title="Missing scopes error">
    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`.
  </Accordion>

  <Accordion title="GraphQL errors or type issues">
    Regenerate the GraphQL types:

    ```bash theme={null}
    npm run graphql-codegen
    ```

    This updates type definitions from Shopify's Admin API schema.
  </Accordion>
</AccordionGroup>

<Note>
  For more detailed setup instructions and advanced configuration, see the [Installation Guide](/installation).
</Note>