Building a subscriptions app

Anchor to Getting startedGetting 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.
Install your app on a dev store.

Anchor to RequirementsRequirements

You're a user with app development permissions and have created a dev store.

You're using the latest version of Shopify CLI.
You're using the latest version of Chrome or Firefox.

You've installed Node.js 20.10 or higher.

Anchor to Quick startQuick start

To quickly create a new subscriptions app, use the Shopify CLI and run the installation command.

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 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.

Anchor to Scopes requestScopes 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, under your app's API access request the following 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.
Protected customer data access, select and save App functionality for all Protected customer data and Protected customer fields (optional) sections, see the following documentation 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

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"

Anchor to Launch the applicationLaunch 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:

Terminal

shopify app dev

In a separate terminal, run the following command to update the webhooks urls by deploying your app:

Terminal

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.

Anchor to Additional configurationAdditional configuration

Anchor to Add App ID environment variableAdd 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, 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/<NUMBER>
Alternatively you can also get this number with an authenticated client query on the Admin API after the app is installed to a test shop. This number is unique across all Shops.
Create a .env file, and add APP_GID=<YOUR_COMPLETE_GID> to it.

Anchor to GraphQL codegenGraphQL codegen

This app uses 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.

.env

SHOPIFY_API_KEY={Client_ID}

To run the GraphQL Codegen that will generate the types, run the following command:

Terminal

npm run graphql-codegen

yarn graphql-codegen

pnpm graphql-codegen

To generate GraphQL types for the customer extension, run:

Terminal

npm run graphql-codegen --project shopifyCustomerApi

yarn graphql-codegen --project shopifyCustomerApi

pnpm run graphql-codegen --project shopifyCustomerApi

And for the admin UI extension:

Terminal

npm run graphql-codegen --project adminSubsActionExtension

yarn graphql-codegen --project adminSubsActionExtension

pnpm run graphql-codegen --project adminSubsActionExtension

Anchor to Next stepsNext 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.