Getting started
You're ready to create a checkout extension. You want to set up your development environment so that you can start coding.
In this tutorial, you'll use Shopify CLI to create a checkout extension. Shopify CLI generates starter code for building your extension and automates common development tasks.
You'll create a simple extension that renders some text in the checkout flow. You can build up this extension for more complex use cases.
TODO: This asset should be updated, the boilerplate extension no longer includes a Order note field, just text that says
Welcome to the Checkout::Dynamic::Render extension!
. It is shown by default in the cart area, underneath the line items.
What you'll learn
Anchor link to section titled "What you'll learn"In this tutorial, you'll learn how to do the following tasks:
Create a new extension
Run the extension locally and test it on a development store
Register the extension with Shopify
Requirements
Anchor link to section titled "Requirements"You've created a Partner account.
You've installed the Shopify CLI.
You've created a new development store, where you've enabled the checkout extensions developer preview.
You've created an app for your checkout extension.
You have basic familiarity with React and vanilla JavaScript (JS).
Step 1: Create a new extension
Anchor link to section titled "Step 1: Create a new extension"You'll use Shopify CLI to scaffold a new extension. In a subsequent step, you'll register the extension with your app.
Navigate to the directory where you want to create your extension.
Authenticate with Shopify CLI:
Create the checkout extension:
At the prompt, choose the app for the extension.
Select Checkout Extension as the type of extension.
Select a template for your extension. You can choose from vanilla JavaScript or React, and whether you want to use TypeScript.
Provide a name for your extension using either dash case or snake case.
You should now have a new project directory that includes the extension script at src/index.{fix-extension}
Review the extension code
Anchor link to section titled "Review the extension code"Shopify CLI creates the following directory structure for the extension:
src/index.{file-extension}
contains boilerplate checkout extension code in the language that you specified when you created the extension.locales
contains JSON-formatted translation strings for checkout localization.extension.config.yml
contains configurations for the checkout extension, including extension points.Checkout::Dynamic::Render
is the extension point for rendering dynamic content in the checkout flow.
The following is an example of the files in the directory:
Step 2: Run your extension
Anchor link to section titled "Step 2: Run your extension"Now you'll use Shopify CLI to run your extension locally. CLI version 2.2.0 and higher creates a test checkout link when there are products in your development store.
Navigate to the folder that contains your extension.
Start the app extension server and follow the command prompts.
If this is the first time testing your extension, then follow the prompt in the CLI output to log in to your development store.
Click on the URL printed at the bottom of the CLI output to view your extension.
Available CLI options
Anchor link to section titled "Available CLI options"--tunnel: Creates an HTTP tunnel (this is the default behavior).
--no-tunnel: Skips creating an HTTP tunnel.
--resourceUrl: A partial link with a product variant ID and quantity to be used to create a test checkout. If the flag isn't passed, then Shopify CLI auto-populates this value. To test with a specific product variant ID and quantity, you can provide the flag as
shopify extension serve --resourceUrl="/12345:1"
, where12345
is the product variant ID and:1
is the quantity.
Step 3: Register the extension
Anchor link to section titled "Step 3: Register the extension"In this step, you'll register the checkout extension with your app.
Step 4: Push the extension
Anchor link to section titled "Step 4: Push the extension"After you've registered your extension to an app, you can push your extension code with Shopify. To publish your extension to Shopify, you need to request network access.
Add the
network_access
Boolean key to your extension configuration file:Push your extension code to Shopify:
Troubleshooting
Anchor link to section titled "Troubleshooting"This section describes how to solve some potential errors when you run shopify extension serve
.
Property token error
Anchor link to section titled "Property token error"If you receive the error ShopifyCLI:AdminAPI requires the property token to be set
, then you'll need to use the --resourceUrl
flag to direct the CLI to open a checkout session for you.
Missing checkout link
Anchor link to section titled "Missing checkout link"If you don't receive the test checkout URL when you run shopify extension serve
, then verify the following:
You have a development store populated with products.
You're logged in to the correct Partners organization and development store. To verify, run
shopify login --store=YOUR-STORE-URL
.
Otherwise, you can manually create a checkout with the following steps:
From your development store's storefront, add some products to your cart.
From the cart, click Checkout.
From your extension project's root, start the app extension server:
You should see similar output to the following:
On the checkout page for your store, change the URL by appending the
?dev=https://{ngrok_tunnel_id}.ngrok.io/extensions
query string and reload the page.You should now see a rendered order note that corresponds to the code in your project template.
TODO: This asset should be updated, the boilerplate extension no longer includes a Order note field, just text that says
Welcome to the Checkout::Dynamic::Render extension!
. It is shown by default in the cart area, underneath the line items.
- Learn how to add custom banners to checkout.