Quick Start Guide

Most partners use the auto-setup approach because it is the fastest path to production. This guide covers the full data-attribute setup and all supported combinations.

1) Main script tag

The main SDK auto-initializes when it finds a script tag with data-liquid-commerce-elements.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Core configuration

Attribute: data-liquid-commerce-elements Marks the script tag for auto-initialization.

Attribute: data-token (required) Your API key.

Attribute: data-env (optional) development, staging, or production (default: production).

2) Product injection options

You can inject products in three different ways. All can be used together.

A) Paired attributes on the main script tag

Use data-product-* with data-container-* pairs.

Attribute: data-product-* + data-container-* Pairs product identifiers to container IDs by matching the numeric suffix.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  data-container-1="product-1"
  data-product-1="00619947000020"
  data-container-2="product-2"
  data-product-2="08504405135"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

<div id="product-1"></div>
<div id="product-2"></div>

B) Attributed product elements

Any div with data-lce-product is treated as a product container.

Attribute: data-lce-product Injects a product into the element and auto-generates a container ID.

<div data-lce-product="00619947000020"></div>
<div data-lce-product="08504405135"></div>

The SDK auto-generates unique container IDs for these elements.

C) JSON script tag

Provide an array of objects with containerId and identifier.

Attribute: data-liquid-commerce-elements-products Reads a JSON array of product definitions.

<script data-liquid-commerce-elements-products type="application/json">
[
  { "containerId": "product-1", "identifier": "00619947000020" },
  { "containerId": "product-2", "identifier": "08504405135" }
]
</script>

3) Cart options (auto-UI + custom UI)

Cart buttons are configured from the main script tag.

Basic cart button

Attribute: data-cart-button Renders a cart button in the specified container (by ID or selector).

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-button="header-cart"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

<div id="header-cart"></div>

Cart button with badge

Attribute: data-cart-badge-button Renders a cart button with item count badge.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-badge-button="header-cart"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Floating cart button

Provide the attribute with no value.

Attribute: data-cart-button (no value) Creates a floating cart button.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-button
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Positioning cart buttons

You can position the cart button relative to any element using:

• inside: (default)

• above:

• below:

• replace:

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-button="above:.nav"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Mobile-specific cart buttons

Use the mobile attributes to target mobile placement separately:

• data-cart-mobile-button

• data-cart-mobile-badge-button

Attribute: data-cart-mobile-button Places a mobile-specific cart button.

Attribute: data-cart-mobile-badge-button Places a mobile-specific cart button with badge.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-mobile-button="inside:#mobile-nav"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Hide cart buttons entirely

Attribute: data-cart-button-hidden Disables auto-created cart buttons.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-button-hidden
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Cart toggle buttons (custom UI)

Any element with data-lce-cart-toggle-button will toggle the cart drawer.

Attribute: data-lce-cart-toggle-button Toggles the cart drawer on click.

<button data-lce-cart-toggle-button>View Cart</button>

Cart items count (custom UI)

Use data-lce-cart-items-count on any element to show item count.

Attribute: data-lce-cart-items-count Renders a live cart item count.

<span data-lce-cart-items-count></span>

By default it hides when the cart is empty. To keep it visible with 0, set:

<span data-lce-cart-items-count="keep-zero"></span>

4) Checkout (hosted injection + checkout-only build)

Hosted checkout needs two things working together:

1. A checkout URL so the cart can redirect to your hosted checkout page.

2. A checkout param name so the hosted page can read the checkout ID from the URL and load it.

Checkout container

Attribute: data-lce-checkout Injects the hosted checkout into this container on the checkout page.

<div data-lce-checkout></div>

Hide checkout header

Attribute: hide-header Hides the SDK header so you can render your own header and layout.

<div data-lce-checkout hide-header></div>

Exit checkout button

Attribute: data-lce-exit-checkout Lets you build your own “Exit checkout” UI. The SDK wires the click to the checkout exit action.

<button data-lce-exit-checkout>Exit checkout</button>

Checkout ID from query params (required for hosted checkout)

Use data-checkout-param on the script tag to control which query param provides the checkout ID. Attribute: data-checkout-param Sets the query parameter name (must start with lce_). The hosted page reads this param to load the checkout.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-checkout-param="lce_checkout"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Notes:

• Query parameter names must start with lce_ or they are ignored.

• Default is lce_checkout if not provided.

Checkout redirect URL (required for hosted checkout)

Attribute: data-checkout-url Defines the hosted checkout page URL pattern. The cart drawer redirects to this URL and injects the checkout token into {token}.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  data-checkout-url="https://yoursite.com/checkout?lce_checkout={token}"
  data-checkout-param="lce_checkout"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Checkout-only auto-initialize

Use the checkout-only build when you only need checkout on the hosted checkout page. It supports the same hosted-checkout attributes (data-lce-checkout, data-checkout-param, hide-header, data-lce-exit-checkout) but ships a smaller script for faster load time.

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
></script>

Supported attributes on checkout-only script:

• data-token (required)

• data-env (optional)

• data-debug-mode (optional, non-production only)

• data-checkout-url (optional)

The checkout-only build also supports data-lce-checkout containers and data-checkout-param query parameter handling.

5) Auto actions from query parameters

Auto-init can read query params to add a product or apply a promo code.

Add product to cart via query params

• data-product-param (required)

• data-product-fulfillment-type-param (optional, shipping or onDemand)

Attribute: data-product-param Name of query param that contains the product identifier (must start with lce_).

Attribute: data-product-fulfillment-type-param Name of query param that contains fulfillment type (must start with lce_).

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-product-param="lce_product"
  data-product-fulfillment-type-param="lce_fulfillment"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Example URL:

https://yoursite.com?lce_product=00619947000020&lce_fulfillment=shipping

Apply promo code via query params

• data-promo-code-param

Attribute: data-promo-code-param Name of query param that contains the promo code (must start with lce_).

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-promo-code-param="lce_promo"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Example URL:

https://yoursite.com?lce_promo=SUMMER20

Notes:

• Query parameter names must start with lce_ or they are ignored.

6) Advanced script options (optional)

These are supported but not required for most implementations.

Promo ticker

All four of these must be present to enable the promo ticker.

Attributes: data-promo-code, data-promo-text, data-promo-separator, data-promo-active-from, data-promo-active-until Enables the promo ticker. data-promo-text is pipe-separated (e.g. "Text A|Text B").

<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  data-promo-code="SUMMER20"
  data-promo-text="20% Off|Free shipping over $50"
  data-promo-separator="•"
  data-promo-active-from="2026-06-01T00:00:00Z"
  data-promo-active-until="2026-08-31T23:59:59Z"
  type="text/javascript"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Development config

For local development or testing, you can inject development overrides via a JSON script tag:

Attribute: data-liquid-commerce-elements-development Reads JSON for development overrides.

<script data-liquid-commerce-elements-development type="application/json">
{
  "customApiUrl": "http://localhost:3000/api",
  "paymentMethodId": "pm_test_123",
  "openShadowDom": true
}
</script>