# 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`.

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/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.

```html
<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://elements.reservebar-worker.workers.dev/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.

```html
<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.

```html
<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).

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-button="header-cart"
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/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.

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-badge-button="header-cart"
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
></script>
```

### Floating cart button

Provide the attribute with no value.

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

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-button
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
></script>
```

### Positioning cart buttons

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

* `inside:` (default)
* `above:`
* `below:`
* `replace:`

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-button="above:.nav"
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/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.

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-mobile-button="inside:#mobile-nav"
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
></script>
```

### Hide cart buttons entirely

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

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-cart-button-hidden
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/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.

```html
<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.

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

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

```html
<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.

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

### Hide checkout header

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

```html
<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.

```html
<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.

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-checkout-param="lce_checkout"
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/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}`.

```html
<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://elements.reservebar-worker.workers.dev/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.

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/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_`).

```html
<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://elements.reservebar-worker.workers.dev/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_`).

```html
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-promo-code-param="lce_promo"
  type="text/javascript"
  src="https://elements.reservebar-worker.workers.dev/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"`).

```html
<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://elements.reservebar-worker.workers.dev/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.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.liquidcommerce.cloud/elements-v2/quick-start-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.