--- title: Building a subscriptions app description: Briefly describe how the reader will benefit from learning the information on this page, and keep it to (roughly) Tweet-length, like this. source_url: html: https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building md: https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building.md --- ExpandOn this page * [Getting started](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#getting-started) * [Scopes request](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#scopes-request) * [Launch the application](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#launch-the-application) * [Additional configuration](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#additional-configuration) * [Next steps](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#next-steps) # Building a subscriptions app *** ## 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](https://shopify.dev/docs/api/shopify-cli). * Install your app on a [development store](https://shopify.dev/docs/api/development-stores#create-a-development-store-to-test-your-app). ### Requirements * You're a [user with app development permissions](https://shopify.dev/docs/apps/build/dev-dashboard/user-permissions) and have created a [development store](https://shopify.dev/docs/api/development-stores). * 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. ## Terminal ```terminal 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](https://shopify.dev/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](https://shopify.dev/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](https://shopify.dev/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](https://shopify.dev/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: ## shopify.app.toml ```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, run the `app dev` command: ## Terminal ```terminal shopify app dev ``` 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. ### Graph​QL 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](https://shopify.dev/docs/api/shopify-app-remix/latest/guide-graphql-types). ## .env ```env SHOPIFY_API_KEY={Client_ID} ``` To run the GraphQL Codegen that will generate the types, run the following command: ## Terminal ```terminal npm run graphql-codegen ``` ```terminal yarn graphql-codegen ``` ```terminal pnpm graphql-codegen ``` ##### npm ``` npm run graphql-codegen ``` ##### Yarn ``` yarn graphql-codegen ``` ##### pnpm ``` pnpm graphql-codegen ``` To generate GraphQL types for the [customer extension](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/extensions#full-page-extension), run: ## Terminal ```terminal npm run graphql-codegen --project shopifyCustomerApi ``` ```terminal yarn graphql-codegen --project shopifyCustomerApi ``` ```terminal pnpm run graphql-codegen --project shopifyCustomerApi ``` ##### npm ``` npm run graphql-codegen --project shopifyCustomerApi ``` ##### Yarn ``` yarn graphql-codegen --project shopifyCustomerApi ``` ##### pnpm ``` pnpm run graphql-codegen --project shopifyCustomerApi ``` And for the admin UI extension: ## Terminal ```terminal npm run graphql-codegen --project adminSubsActionExtension ``` ```terminal yarn graphql-codegen --project adminSubsActionExtension ``` ```terminal pnpm run graphql-codegen --project adminSubsActionExtension ``` ##### npm ``` npm run graphql-codegen --project adminSubsActionExtension ``` ##### Yarn ``` yarn graphql-codegen --project adminSubsActionExtension ``` ##### 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](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/core-system-components). ### Developer tools and resources [![](https://shopify.dev/images/icons/48/clicode.png)![](https://shopify.dev/images/icons/48/clicode-dark.png)](https://github.com/Shopify/subscriptions-reference-app) [GitHub](https://github.com/Shopify/subscriptions-reference-app) [You can also view the repository on GitHub.](https://github.com/Shopify/subscriptions-reference-app) [![](https://shopify.dev/images/icons/48/graphql.png)![](https://shopify.dev/images/icons/48/graphql-dark.png)](https://shopify.dev/docs/api/shopify-app-remix/latest/guide-graphql-types) [Typing GraphQL operations](https://shopify.dev/docs/api/shopify-app-remix/latest/guide-graphql-types) [Learn how to type GraphQL operations in the Shopify Subscriptions Reference app.](https://shopify.dev/docs/api/shopify-app-remix/latest/guide-graphql-types) [![](https://shopify.dev/images/icons/48/themes.png)![](https://shopify.dev/images/icons/48/themes-dark.png)](https://shopify.dev/docs/apps/design) [App Design Guidelines](https://shopify.dev/docs/apps/design) [Directives to show you what great Shopify apps look like and how they're crafted.](https://shopify.dev/docs/apps/design) [![](https://shopify.dev/images/icons/48/bfsgem.png)![](https://shopify.dev/images/icons/48/bfsgem-dark.png)](https://shopify.dev/docs/apps/launch/built-for-shopify) [Built for Shopify](https://shopify.dev/docs/apps/launch/built-for-shopify) [Learn more about the Built for Shopify program.](https://shopify.dev/docs/apps/launch/built-for-shopify) *** * [Getting started](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#getting-started) * [Scopes request](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#scopes-request) * [Launch the application](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#launch-the-application) * [Additional configuration](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#additional-configuration) * [Next steps](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/subscriptions-app/start-building#next-steps)