Skip to main content

Checkout Extension Development Guide

Overview​

Checkout Extension allows developers to inject custom content and business logic into the store checkout page without modifying theme code.

A Checkout Extension developed using the shoplazza app command supports the following two capabilities:

  • Insert custom content at specified extension points: Render custom HTML at fixed positions on the checkout page — for example, displaying a prompt banner above contact information or adding explanatory text below the payment module.

  • Read checkout data and respond to changes: Use the CheckoutAPI to obtain order, product, price, address, user, and other information, and listen for changes to execute custom logic.

Development Methods Explained​

  • Develop in an empty directory: The generated extension can only be used by your own store and cannot be published for other merchants.

  • Develop in an existing app project: Publish the extension as part of an app that other merchants can install and use. For a complete app development tutorial, see the App Development Guide.

What You'll Learn​

  • How to initialize and create a Checkout Extension using the CLI

  • How to select an extension point and render custom content at a specific position on the checkout page

  • How to use extend with an HTML template to create a minimal previewable extension

Prerequisites​

  • shoplazza-cli installed

  • A Shoplazza developer account

  • An existing shoplazza app project, or an empty directory for development

Development Workflow​

Step 1: Initialize​

Run the following command in your app project root (or empty directory):

shoplazza app init

Follow the prompts to create a new app or select a bound app (e.g., my-app). After completion, a subdirectory named after the app will be created in the current directory.

Step 2: Create a Checkout Extension​

Navigate to the generated app directory and run:

shoplazza app generate extension

Follow the prompts:

  1. Select the extension type: checkout

  2. Enter the extension name (e.g., my-checkout)

After generation, the directory structure will look like this:

my-app/
└── extensions/
    └── my-checkout/
        ├── shoplazza.extension.toml   # Extension configuration file
        ├── package.json
        └── src/
            ├── index.js               # Extension entry point
            ├── index.html             # Main HTML template
            ├── style.html             # Styles
            ├── content.html           # Page content
            └── script.html            # Script logic

Develop your extension under the src/ directory.

Step 3: Start a Preview​

After development, run the following command in the app directory:

shoplazza app dev

The extension will be automatically published to the bound store. You can then view the result in the store theme editor's "Checkout Editor."

Extension Points Overview​

Extension points determine the specific position on the checkout page where custom content is inserted. Specify the extension point in the extensionPoint field of extend(). Common extension points:

Extension PointDescription
Checkout::RenderBeforeBefore the page header
Checkout::ContactInformation::RenderAfterAfter the contact information module
Checkout::Summary::RenderBeforeBefore the order summary
Checkout::SectionPayment::RenderBeforeBefore the payment module

For a full list of extension points, see the Checkout Extension Reference.

A Minimal UI Example​

Import extend from shoplazza-extension-ui, specify an extension point, and pass an HTML string to render content on the checkout page:

import { extend } from 'shoplazza-extension-ui';

extend({
  extensionPoint: 'Checkout::RenderBefore',
  component: '<div style="padding:12px;background:#f5f5f5;">Hello, Shoplazza!</div>',
});

For more complex content, you can split it into src/style.html / src/content.html / src/script.html and assemble them in src/index.html. For the extend function signature, HTML template mechanism, and the full Checkout API, see the Checkout Extension Reference.

Don't forget semicolons

Each statement in JavaScript files must end with a semicolon. If a semicolon is missing, the dev runtime will throw an error and misleadingly indicate that extend must be written at the top of the file. This is caused by parsing failure and is not a problem with the position of extend.

Preview and Publish​

Run the following command in the app directory:

shoplazza app dev

After the extension is automatically published to the bound store, open the store admin's "Checkout Editor" to preview the result.

If you want other merchants to be able to use the extension, you must first complete the app development and then publish it:

shoplazza app deploy

After other merchants install the app, they can preview the extension in their store theme editor's checkout page.

Next Steps​