Get started building a product subscription app extension

This tutorial explains how to get started building a product subscription app extension using App Bridge Admin. For more information on the business logic behind subscriptions, refer to the Selling plan API.

How a product subscription app extension looks in Shopify

Shopify renders a new section, called a subscription card, on the product page to display subscription information to the merchant:

App Bridge Admin card on product page

If a merchant clicks Add option, then an app overlay appears. Your extension built with App Bridge Admin is responsible for rendering the content and creating the subscription plan.

Scaffold a product subscription app extension

You can use Shopify CLI to create a product subscription app extension scaffold.

  1. Open a terminal and enter the following command to create a new product subscription app extension:

  2. Follow the instructions in order to scaffold your product subscription app extension.

You should now have a new project folder, where you can find the extension script at either ./index.ts(x) or ./index.js.

Run the local extension in your development store

To run your extension in your development store you:

  1. Navigate to the project folder and start a local server to make the extension available to your development store:

  2. Follow the prompts to associate your extension to your app and development store.

  3. Navigate to the ngrok tunnel URL that is output in the terminal to open the product page in your development store.

If you don't have any products on your development store, then you can either manually create one or run the following command in your project's folder to generate 5 mock products in your development store:

Building your extension

Now that you have your local extension running in your development store, you can iterate on it.

Click the Developer Console navigation option.

Developer Console navigation item

You should see the green Connected status badge along with other data related to your extension.

Developer Console

You should also see a card titled "Subscriptions" on the product page. You might need to scroll down to see it.

Developer console with subscriptions card

For more information on rendering extension points, refer to Create and manage a product subscription app extension.

You can update the extension script at either ./index.ts(x) or ./index.js and test it in your development store.

Mobile testing

You can test your extension in the Shopify mobile app using the developer console:

  1. Log into your development store on the Shopify mobile app.

  2. In the browser, click on the mobile icon in the Developer Console to generate a QR code. Developer console mobile QR code

  3. Use the camera on your mobile device or a QR code scanning app of your choice to scan the QR code from the Developer Console to open the product details view on the Shopify mobile app. Your extension is available in the subscriptions card.

    Mobile subscription extension

Extension points

The product subscription app extension uses multiple extension points. Each extension point is triggered by a different merchant action, receives different data, and is responsible for handling a distinct part of the subscription experience. For more information on the available extension modes, refer to Create and manage a product subscription app extension.

The different extension points are:

  • Admin::Product::SubscriptionPlan::Add
  • Admin::Product::SubscriptionPlan::Create
  • Admin::Product::SubscriptionPlan::Edit
  • Admin::Product::SubscriptionPlan::Remove

They must be rendered separately.

Javascript:

React:

Data

Your extension receives data from the host page in your extension. In this example, the current product is being rendered inside the extension as (Product 1):

App Bridge Admin subscriptions app overlay

In src/index.tsx or src/index.js, find the Create extension point callback function. In the first line of the function, the data variable is assigned to the input data passed into the extension from the host page.

Javascript:

In vanilla JavaScript, input data is passed into the extension point callback function:

Refer to the full source for the JavaScript product subscription app extension template.

React:

In React, access input data with the useData hook:

Refer to the full source for the React product subscription app extension template.

Components

The final section of the Create function renders the UI components that appear in the canvas of the app overlay. Refer to components available to the product subscription app extension.

App Bridge Admin subscriptions app overlay

Javascript:

Refer to the full source for the JavaScript product subscription app extension template.

React:

Refer to the full source for the React product subscription app extension template.

Upgrading

To upgrade from using the simulator to using the Developer Console:

  1. Upgrade the Shopify CLI

  2. Update the admin-ui-extensions-run package

    NPM

    Yarn

  3. Restart your extension server

Next steps