Start building purchase options extensions

You can add subscriptions, pre-order, and try-before-you-buy (TBYB) functionality by creating a purchase options extension. A purchase options extension is a type of Admin UI extension.

The Admin action extensions use the following targets:

• admin.product-purchase-option.action.render
• admin.product-variant-purchase-option.action.render

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

• Create a purchase options Admin UI extension
• Run the extension locally and test it on a development store.

Anchor to RequirementsRequirements

• Public apps that use subscriptions, pre-order, or TBYB need to meet specific requirements to be published on the Shopify App Store.
• Custom apps created in the Shopify admin can't use subscriptions, pre-order, or TBYB because these apps can't use extensions or request access to protected scopes. If you're building a solution for a single store, then build your custom app in the Partner Dashboard.
• You've created a Partner account.
• You've created a development store that uses generated test data.
• You've created an app that uses Shopify CLI 3.0 or higher.
• Your app has the necessary access scopes to use the GraphQL Admin API for purchase options.

Anchor to Step 1: Generate a new extensionStep 1: Generate a new extension

1. Use Shopify CLI to generate a new extension:

   Terminal

   Copy

   $

   $

   shopify app generate extension --template admin_purchase_option --name purchase-options-action --flavor react

You should now have a new extension directory at extensions/purchase-options-action.

2. Navigate to extensions/purchase-options-action/shopify.extension.toml and make sure the targets are shown as the following codeblock. This ensures that the admin action is rendered correctly on the product and product variant page:

   extensions/purchase-options-action/src/PurchaseOptionsActionExtension.tsx

   Copy

   9

   1

   2

   3

   4

   5

   6

   7

   [[extensions.targeting]]

   module = "./src/ActionExtension.tsx"

   target = "admin.product-purchase-option.action.render"

   
   

   [[extensions.targeting]]

   module = "./src/ActionExtension.tsx"

   target = "admin.product-variant-purchase-option.action.render"

Anchor to Step 2: Run the extensionStep 2: Run the extension

1. To preview the extension, either start or restart your server with the following command:

   Terminal

   Copy

   $

   $

   shopify app dev

2. Press p to open the developer console.

3. In the developer console page, click on the preview link for the subscription action extension.

4. To launch your extension, on the purchase options card, click Subscriptions, preorders, try before you buy, and more and select create new or select your app if you have multiple apps installed. You should see the extension on the product page.

Anchor to Step 3: Create and manage subscriptionsStep 3: Create and manage subscriptions

When working with the purchase options admin action, the Shopify admin renders an extension when a merchant wants to create or edit a purchase option. Shopify provides the following information when a merchant triggers the action:

The id represents the product ID or the product variant ID, depending on the page the merchant is currently on. The sellingPlanId represents the selling plan group ID attached to the product or the product variant that the merchant would like to edit. The sellingPlanId is empty when a merchant wants to create a new purchase option from the product or product variant page.

To retrieve the product ID and selling plan group ID, refer to the data's Action Extension API that contains the data passed from Shopify to the admin action extension.

Anchor to Create, edit and query a purchase optionCreate, edit and query a purchase option

When you're writing extensions, you don't need proxy calls to the GraphQL Admin API through your app's backend. Instead, your extension can use direct API access to create requests directly using fetch. This helps extensions be more performant and responsive for merchants.

You can use the sellingPlanGroupsCreate mutation to create a new purchase option and the sellingPlanGroupsUpdate mutation to update an existing purchase option. You can query a selling plan group with the sellingPlanGroup query.

The Shopify's Subscriptions Reference App has a full code source that shows how you can render a complete Admin UI extension.

Anchor to Developer tools and resourcesDeveloper tools and resources

At Shopify, we deeply care about the experience merchants have on their store's admin, and we want partners to have the same care for merchants when it comes to creating experiences for their application and extensions. Read on to create the best experience for merchants:

Design guidelines for admin apps

Learn the design guidelines for building apps in the Shopify admin.

Admin extensions UI kit

The Figma UI kit contains components, screens, and examples to help you build and understand admin UI extensions.