## Getting started This guide describes in greater depth the Shopify Subscriptions Reference app. In this guide, you'll learn how to do the following tasks: * Initialize the Shopify Subscriptions Reference app that uses the latest version of the [Shopify CLI](/docs/api/shopify-cli). * Install your app on a [development store](/docs/api/development-stores#create-a-development-store-to-test-your-app). ### Requirements * You've created a [Partner account](https://www.shopify.com/partners). * You've created a development store. * You've installed [Node.js](https://nodejs.org/en/download) 20.10 or higher. ### Quick start To quickly create a new subscriptions app, use the Shopify CLI and run the installation command. ```bash shopify app init --template https://github.com/Shopify/subscriptions-reference-app ``` This command clones the Shopify Subscription App repository and installs all the dependencies needed to run the app. > Note: > In addition to the Admin embedded app, the reference app integrates with Shopify in different ways to enhance both merchant and customer experience. Learn more about the [extensions included in this template](/docs/apps/build/purchase-options/subscriptions/subscriptions-app/extensions). ## Scopes request The Shopify Subscriptions Reference app requires a set of scopes to run that must be approved by Shopify because they provide access to protected data. In your [Partner's dashboard](https://partners.shopify.com/), under your app's API access [request the following access scopes](/docs/api/usage/access-scopes#authenticated-access-scopes): * Request the Read all orders scope, which gives access to `read_all_orders`. * Access subscriptions APIs, which gives you access to `write_own_subscription_contracts` and `read_customer_payment_methods` scopes. Learn more about [Subscriptions contracts](/docs/apps/build/purchase-options/subscriptions/contracts). * Protected customer data access, select and save `App functionality` for all `Protected customer data` and `Protected customer fields (optional)` sections, see the [following documentation](/docs/apps/launch/protected-customer-data#request-access-to-protected-customer-data) for instructions on how to proceed. This will give you access to the following scopes: * `read_customer_address` * `read_customer_email` * `read_customer_name` * `read_customer_personal_data` * `read_customer_phone` * Access to allow network access in checkout and account UI extensions that will give you access to the `read_checkout_external_data` scope. > Caution: > The request for some scopes can take up to **7 business days** to be approved. Once all the scopes are approved, set the scopes configuration to your `shopify.app.toml` file as follows: ```toml scopes = "customer_read_orders,customer_write_customers,customer_write_own_subscription_contracts,read_all_orders,read_locales,read_locations,read_themes,read_customer_payment_methods,write_customers,write_metaobject_definitions,write_metaobjects,write_orders,write_products,write_translations,write_own_subscription_contracts" ``` ## Launch the application Once you have all the scopes required to launch the Shopify Subscriptions Reference app, you can launch the app. To view your application, we are using the Shopify CLI: ```bash shopify app dev ``` In a separate terminal, run the following command to update the webhooks urls by deploying your app: ```bash shopify app deploy ``` On your app dev terminal, you can press `p` to open the dev console and view the app and the available extensions. ## Additional configuration ### Add App ID environment variable Some background jobs (ie. `CreateSellingPlanTranslationsJob`) use your app ID to filter out all events that are not from your app. It's important to update the `APP_GID` environment variable to your app's ID to ensure proper functionality. * Locate your app GID by opening the [Partners dashboard](https://partners.shopify.com/), apps, selecting your app in the list. * Look for the number in the URL after `/apps/`. This is your GID and you can use it to build the app GID in the following format: `gid://shopify/App/` * Alternatively you can also get this number with an [authenticated client query on the Admin API](https://shopify.dev/docs/api/admin-graphql/2024-10/queries/app) after the app is installed to a test shop. This number is unique across all Shops. * Create a `.env` file, and add `APP_GID=` to it. ### GraphQL codegen This app uses [GraphQL Codegen](https://the-guild.dev/graphql/codegen) to create TypeScript types from the Shopify GraphQL schema, ensuring data returned from Shopify is automatically typed. To generate Shopify GraphQL types, configure GraphQL Codegen to output the types into a types folder using the `.graphqlrc.ts` file. Ensure your environment variables include `SHOPIFY_API_KEY`, which is your App Client ID (that can be found by clicking on your app in Shopify Partners), so that codegen creates types from your app's queries and mutations. You will find more information on [Typing GraphQL Operations documentation page](/docs/api/shopify-app-remix/v2/guide-graphql-types). ```env SHOPIFY_API_KEY={Client_ID} ``` To run the GraphQL Codegen that will generate the types, run the following command: ```bash?title: 'npm' npm run graphql-codegen ``` ```bash?title: 'Yarn' yarn graphql-codegen ``` ```bash?title: 'pnpm' pnpm graphql-codegen ``` To generate GraphQL types for the [customer extension](/docs/apps/build/purchase-options/subscriptions/subscriptions-app/extensions#full-page-extension), run: ```bash?title: 'npm' npm run graphql-codegen --project shopifyCustomerApi ``` ```bash?title: 'Yarn' yarn graphql-codegen --project shopifyCustomerApi ``` ```bash?title: 'pnpm' pnpm run graphql-codegen --project shopifyCustomerApi ``` And for the admin UI extension: ```bash?title: 'npm' npm run graphql-codegen --project adminSubsActionExtension ``` ```bash?title: 'Yarn' yarn graphql-codegen --project adminSubsActionExtension ``` ```bash?title: 'pnpm' pnpm run graphql-codegen --project adminSubsActionExtension ``` ## Next steps The following steps describe the core components and extensions of the Shopify Subscriptions Reference app and how they work together. Learn more about the [core Shopify Subscriptions Reference app components](/docs/apps/build/purchase-options/subscriptions/subscriptions-app/core-system-components). ### Developer tools and resources

GitHub

You can also view the repository on GitHub.

Typing GraphQL operations

Learn how to type GraphQL operations in the Shopify Subscriptions Reference app.

App Design Guidelines

Directives to show you what great Shopify apps look like and how they’re crafted.

Built for Shopify

Learn more about the Built for Shopify program.