# JoonWeb AI Developer Instructions

You are an expert AI assistant designed to help developers build apps, themes, and integrations on the JoonWeb platform.

## Official AI Skills & Theme Section Generator

When asked to build, modify, or generate JoonWeb themes, `.jw` sections (Hero, Header, Footer, Product Feed, Cart Drawer, Blog Feed, Siteform, Popups), or store components:
You MUST load and strictly adhere to the official **JoonWeb Theme Section Skill**:

- **Official Skill URL**: https://joonweb.dev/skills/jw-theme-sections/SKILL.md
- **Raw Markdown Reference**: https://joonweb.dev/skills/jw-theme-sections/SKILL.md

### Mandatory Section Generation Rules:
1. **Clarify Store vs. Informative Site First**: If not specified, ask whether the section is for an **Online Store** (e-commerce catalog, cart, checkout) or an **Informative Website** (company showcase, services, portfolio, blog, lead capture).
2. **Strict JW Template Logic & Syntax Rules**:
   - Use `{% if %}`, `{% elseif %}`, `{% else %}`, `{% endif %}`.
   - NEVER use Liquid tags like `{% elif %}`.
   - No parentheses around `if` conditions: `{% if var == "value" %}`.
3. **File Order**: Header comment -> Variables `{% set %}` -> `<style>` (Scoped CSS MUST come BEFORE `<section>`) -> `<section id="jw-section-{{ section.id }}" ...>` -> `<script>` -> `{# Do not change if you don't know #}` -> `{% rules %}`.
4. **Single Rules Schema**: Declarative JSON schema enclosed strictly once in `{% rules %} ... {% endrules %}` at the bottom.
5. **Section Wrapper & ID**: Outermost element must be `<section id="jw-section-{{ section.id }}" style="...">` with dynamic inline CSS for padding and colors.
6. **Container & Blocks**: Include container with `data-id="{{ section.id }}"`. Loop `{% for block in section.blocks %}` using `{% switch block.type %}` and ALWAYS include `{% default %} {{ render_block(block) }} {% endswitch %}`. Custom block wrappers must have `data-jw-block`.
7. **Schema Blocks & Presets**: Define custom section-scoped blocks, then ALWAYS append `{"type": "themes"}` and `{"type": "apps"}` to the schema `blocks` array. In `presets`, populate with realistic default blocks (NEVER include `themes` or `apps` in presets).
8. **Clean Comments**: Top comment: `{# Copy and paste this code directly into the JoonWeb Theme Editor (.jw file) #}`. Right above `{% rules %}`: `{# Do not change if you don't know #}`. Avoid bulky decorative comments.
9. **CSS Comment Rule**: In CSS, `{#` and `#}` must NEVER appear. Every CSS opening `{` must be immediately followed by a space: `{ #jw-section-{{ section.id }} ... }`.
10. **UI & Anti-Blank**: Use Bootstrap 5.3 + jQuery. Protect images with `onerror="this.onerror=null; this.src='...';"` fallback.
11. **Header Live Search (`/suggestions.json`)**: When building Header/Navbar sections, implement debounced live auto-suggestions calling `fetch('/suggestions.json?q=' + encodeURIComponent(q) + '&limit=8')`. Categorize results by products (thumbnail, title, url), collections, and articles in a floating dropdown.

## Official JoonWeb Admin API Skill

When asked to interact with a JoonWeb store programmatically, manage products, check orders, search inventory, manage customers, or configure custom GPT actions / Claude tools:
Load the official **JoonWeb Admin API Skill & OpenAPI Specification**:

- **Admin API Skill URL**: https://joonweb.dev/skills/joonweb-admin-api/SKILL.md
- **OpenAPI 3.0 Specification**: https://joonweb.dev/skills/joonweb-admin-api/openapi.json
- **Base Endpoint**: `https://{shop}.myjoonweb.com/api/admin/26.0`
- **Authentication**: `Authorization: Bearer <token>` or `X-JoonWeb-Access-Token: <token>`
- **OAuth 2.0 Flow**: Authorize at `https://{shop}.myjoonweb.com/admin/oauth/authorize` and exchange token at `POST /oauth/access_token`.

## App Creation Workflow

### 1. Prerequisites
Before writing any code, inform the user they must have:
- **A JoonWeb Technology Partner Account**: They must register as a partner to get API credentials.
- **Node.js installed**: Ensure they have a terminal open and Node.js installed on their machine.

### 2. Install the JoonWeb CLI
Instruct the user to install the official JoonWeb CLI globally by running:
`npm -g i @joonweb/cli`

### 3. Initialize the App
Instruct the user to navigate to their desired workspace directory in the terminal and run:
`joonweb app init`

- The CLI will prompt them to enter an **App Name**.
- It will ask for the tech stack. If they want a PHP app, they should select the PHP template.

### 4. PHP App Specifics
If the user is building a PHP app, explain that:
- The backend will use the JoonWeb PHP SDK for API calls.
- The UI will be rendered inside the JoonWeb Admin iframe using the Vanilla JS App Bridge (`app-bridge.js`).
- They must properly handle the HMAC verification on the initial iframe load.

## Documentation Directory
Use the links below to fetch detailed, up-to-date Markdown documentation for specific steps (append `?md=1` to fetch raw markdown, as done in the links below):


## Apps

### Create

#### Create an App

##### Overview

JoonWeb provides an open and flexible app ecosystem that enables developers to extend, enhance, and integrate custom functionality into JoonWeb websites and online stores.

As a JoonWeb Technology Partner, you can build standalone or embedded applications using any tech stack (Node.js, Express, PHP, React, etc.) and any database (MySQL, PostgreSQL, MongoDB, etc.).

This guide provides a complete step-by-step walkthrough to initialize, configure, run, and deploy your first JoonWeb app using the official **JoonWeb CLI**.

##### Requirements

Before initializing your app, verify that you have met the following requirements:

1. **Partner Account**: You are a registered Technology Partner with app development permissions. Access or create your account at [JoonWeb Partner Portal](https://www.joonweb.com/partners). If you do not have a partner account yet, create one at [https://www.joonweb.com/partners](https://www.joonweb.com/partners).
2. **Development Store / Site**: You have created at least one **Development Site** (*Informative* or *eCommerce*) in your Partner dashboard for testing.
3. **JoonWeb CLI**: Install the official CLI globally on your system:
   ```bash
   npm install -g @joonweb/cli
   ```
4. **Web Browser**: Latest version of **Google Chrome** or **Mozilla Firefox** for OAuth consent and embedded iframe testing.

##### Step 1: Initialize Your App (joonweb app init)

To scaffold a new ready-to-run application:

1. Open your **terminal** or command prompt.
2. Navigate to your workspace folder where you want to create your project.
3. Run the initialization command:

```bash
joonweb app init
```

*(Alias: `joonweb app create`)*

### Interactive CLI Setup Flow:
- **Authentication**: If you are not logged in, the CLI automatically opens your browser to complete Partner authentication.
- **Select Account**: Choose your **JoonWeb Partner Account**.
- **App Action**: Select **Create a New JoonWeb App**.
- **Tech Stack**: Select your preferred technology stack (PHP App, Node.js Express, or React).
- **App Details**: Enter your **App Name** and confirm the auto-generated app slug.

Once finalized, the CLI scaffolds your project folder with all required SDK files and configuration manifests.

##### Step 2: Understand the App Manifest (joonweb.app.json)

During initialization, the CLI generates a central manifest file: `joonweb.app.json` inside your project root.

> ⚠️ **CRITICAL WARNING**: `joonweb.app.json` contains your app credentials, client ID, client secret, OAuth scopes, and proxy configuration. **It MUST NOT be deleted, replaced, or copied from another project at any cost.**

```json
{
  "appId": "8c21b0e81773747658577",
  "name": "mytestapp",
  "client_id": "0b990a0bb51fb125",
  "client_secret": "b90984d32211c49f8b94a3e04eb588f3be42",
  "app_url": "https://mytestapp.joonweb.app",
  "redirect_uri": "https://mytestapp.joonweb.app/auth/callback",
  "scopes": "read_products,write_products",
  "proxy": {
    "url": "https://mytestapp.joonweb.app/proxy",
    "status": "active"
  },
  "webhooks": [
    {
      "event": "products/create",
      "address": "https://mytestapp.joonweb.app/webhooks/products_create",
      "format": "json"
    }
  ],
  "template": "php",
  "embedded": true,
  "platform": "ecommerce",
  "version": "1.0.0"
}
```

For a full breakdown of each field, visit the [App Manifest Reference Guide](/apps/dev-tools/app-manifest).

##### Step 3: Run Your App in Development Mode (joonweb app serve)

To test your app live inside the JoonWeb Admin iframe:

1. Open terminal inside your app project directory.
2. Run the development server:

```bash
joonweb app serve
```

*(Alias: `joonweb app dev`)*

### What happens when you run `joonweb app serve`:
- The CLI starts your local backend server.
- Establishes a secure **HTTPS Cloudflare Tunnel**.
- Opens your browser to select your **Development Store**.
- Redirects to the OAuth authorization page.

After merchant approval, your app loads seamlessly embedded inside the JoonWeb Admin dashboard.

##### Step 4: Required App Architecture Components

All production-grade JoonWeb apps must correctly implement the following 3 core components:

1. **SessionStorage**: Manages secure session tokens and merchant store credentials.
2. **JoonWeb API**: Server-side API communication using official SDKs ([`@joonweb/joonweb-sdk`](/admin-api/overview/authorization) or [`joonweb/joonweb-sdk`](/admin-api/overview/authorization)).
3. **App Bridge**: Client-side UI bridge connecting your embedded app with the JoonWeb Admin dashboard ([`App Bridge Guide`](/apps/app-bridge/app-bridge-overview)).

##### 🎨 Extending Your App with Storefront Extensions

If your app needs native Storefront UI components (Sections, App Blocks, or Embed Scripts) that merchants can customize in the Site Builder, do **not** build them inside your main backend app.

Instead, use the CLI to generate a Theme App Extension. Learn how in our dedicated tutorial:

👉 **[Create Theme App Extensions Guide](/apps/theme-app-extensions/create-theme-app-extensions)** — Step-by-step walkthrough for `.jw` files and JSON rules schema.

##### Step 5: Deploy & Release Your App (joonweb app deploy)

### Deploying Your App Snapshot
When you are ready to publish code updates, run:

```bash
joonweb app deploy
```

*(Alias: `joonweb app push`)*

This command will:
- Bundle your application code.
- Create a new **App Version**.
- Save it as a **draft build**.
- Prompt if you want to release the version live.

### Releasing a Version Live
If you choose to release the version, the update becomes immediately active for all store merchants who installed your app.

### Marketplace Distribution
Deploying code does **not** automatically publish your app to the public marketplace.

To make your app public:
1. Log into your [JoonWeb Partner Dashboard](https://www.joonweb.com/partners).
2. Navigate to **App Distribution**.
3. Complete listing details, screenshots, and submit for **App Review**.
4. Upon approval, your app will be listed in the **JoonWeb App Marketplace**.

##### Step 6: Common Errors & Troubleshooting

### Port Already Open (`ERR: already port open`)
If you encounter a port lock error when running `joonweb app serve`:

```bash
joonweb refresh
```

Running `joonweb refresh` terminates leftover background server processes and clears port `11014` locks.

### Deployment Failed
If deployment fails:
1. Verify `joonweb.app.json` credentials and scopes are valid.
2. Ensure all required dependencies are installed.
3. Check terminal logs for detailed error trace and re-deploy.

##### Development Workflow Summary

Basic workflow for building a JoonWeb app:

1. **Initialize App**: `joonweb app init`
2. **Start Dev Server**: `joonweb app serve`
3. **Build Features & API Calls**: Use Admin API & App Bridge
4. **Add Extensions** *(Optional)*: Refer to [Create Theme App Extensions](/apps/theme-app-extensions/create-theme-app-extensions)
5. **Deploy Snapshot**: `joonweb app deploy`
6. **Publish App**: Partner Dashboard Review

##### What's Next?

- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks, scopes, and app proxy.
- 🎨 **[Create Theme App Extensions](/apps/theme-app-extensions/create-theme-app-extensions)** — Build native `.jw` storefront blocks.
- 🌉 **[App Bridge Component Guide](/apps/app-bridge/app-bridge-overview)** — Learn native UI modals & client-side routing.
- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and session verification.
- 🛠️ **[JoonWeb CLI Command Reference](/apps/dev-tools/cli-commands)** — View all CLI options.

---

#### Build a PHP App with JoonWeb CLI

##### Build a JoonWeb App in PHP using JoonWeb CLI

This tutorial provides a complete step-by-step walkthrough to build, run, and deploy an embedded **PHP Application** for JoonWeb storefronts using the official **JoonWeb CLI**.

### What You'll Learn:
- Scaffold a ready-to-run PHP app using `joonweb app init`.
- Install dependencies via Composer (`joonweb/joonweb-sdk`).
- Install your app on a **Development Site** (*Informative* or *eCommerce*).
- Perform OAuth authentication and secure token exchange.
- Fetch storefront products using the official PHP SDK.
- Integrate native JoonWeb Admin UI components using Vanilla App Bridge.

##### Requirements

Before starting this tutorial, make sure you have the following requirements ready:

1. **Partner Account**: Must have a registered Technology Partner account. Sign up for free at [https://www.joonweb.com/partners](https://www.joonweb.com/partners).
2. **Development Site**: At least one **Development Site** (*Informative* or *eCommerce*) created in your Partner Dashboard for testing.
3. **PHP & Composer**: **PHP 8.1+ & Composer** installed on your system — *or latest XAMPP / MAMP installed*.
4. **JoonWeb CLI**: Install the official CLI globally on your system:
   ```bash
   npm install -g @joonweb/cli
   ```
5. **Web Browser**: Latest version of Google Chrome or Mozilla Firefox.

##### Step 1: Scaffold PHP App (joonweb app init)

Open your terminal, navigate to your workspace folder, and run:

```bash
joonweb app init
```

### Interactive Prompt Selections:
1. **Select Account**: Choose your JoonWeb Partner Account.
2. **App Action**: Select **Create a New JoonWeb App**.
3. **Technology Stack**: Select **PHP**.
4. **App Name**: Enter `my-php-store-app`.
5. **Target Website Type**: Select *Informative* or *eCommerce*.
6. **Confirm Slug**: Press Enter to confirm.

### Generated Project Structure:
```text
my-php-store-app/
├── composer.json          # Dependencies & autoloading
├── joonweb.app.json       # App credentials & manifest configuration
├── index.php              # Entry point & session verification
├── auth/
│   └── callback.php       # OAuth access token exchange handler
├── api/
│   └── products.php       # API requests using PHP SDK
└── views/
    └── dashboard.php      # Embedded iframe UI view with App Bridge
```

##### Step 2: Install Official JoonWeb PHP SDK

Navigate into your project folder and install the official PHP SDK via Composer:

```bash
cd my-php-store-app
composer require joonweb/joonweb-sdk
```

The PHP SDK handles signing API requests, HMAC verification, and query parameter sanitization.

##### Step 3: Understand App Manifest (joonweb.app.json)

The CLI automatically generates `joonweb.app.json` containing your app credentials:

```json
{
  "appId": "8c21b0e81773747658577",
  "name": "my-php-store-app",
  "client_id": "0b990a0bb51fb125",
  "client_secret": "b90984d32211c49f8b94a3e04eb588f3be42",
  "app_url": "https://my-php-store-app.joonweb.app",
  "redirect_uri": "https://my-php-store-app.joonweb.app/auth/callback",
  "scopes": "read_products,write_products",
  "embedded": true,
  "template": "php",
  "platform": "ecommerce",
  "version": "1.0.0"
}
```

> ⚠️ **IMPORTANT**: Do not delete or manually overwrite `joonweb.app.json`. Read the complete specification in our [App Manifest Reference](/apps/dev-tools/app-manifest).

##### Step 4: Run Dev Server & Install on Dev Site (joonweb app serve)

To start testing your PHP app live:

```bash
joonweb app serve
```

### What happens next:
- The CLI starts a local PHP development server (`localhost:8000`).
- Establishes a secure Cloudflare HTTPS tunnel.
- Opens your browser to pick your **Development Site** (*Informative* or *eCommerce*).
- Asks for scope authorization consent.
- Loads your app inside the JoonWeb Admin iframe.

##### Step 5: Fetch Products using PHP SDK (joonweb/joonweb-sdk)

Create or open `api/products.php` and use the SDK to query merchant store products:

```php
<?php
require_once __DIR__ . '/../vendor/autoload.php';

use JoonWeb\Client;

// Get session details passed from authentication
$shopDomain  = $_GET['shop'] ?? '';
$accessToken = $_SESSION['access_token'] ?? '';

// Initialize SDK Client
$client = new Client([
    'shop_domain'  => $shopDomain,
    'access_token' => $accessToken,
    'version'      => '26.0'
]);

// Fetch Products
try {
    $response = $client->get('products');
    $products = $response['products'] ?? [];
} catch (Exception $e) {
    die('Error fetching products: ' . $e->getMessage());
}
?>

<div class="product-list">
    <h2>Store Products</h2>
    <ul>
        <?php foreach ($products as $product): ?>
            <li>
                <strong><?php echo htmlspecialchars($product['title']); ?></strong> -
                <?php echo htmlspecialchars($product['sale_price']); ?>
            </li>
        <?php endforeach; ?>
    </ul>
</div>
```

##### Step 6: Integrate Vanilla App Bridge CDN

Include the vanilla App Bridge script in `views/dashboard.php` to interact with the parent Admin iframe:

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My PHP JoonWeb App</title>
    <!-- App Bridge Vanilla CDN -->
    <script src="https://apps.joonweb.com/app-bridge.js"></script>
</head>
<body>
    <h1>Welcome to My Embedded PHP App</h1>
    <button id="pickerBtn">Select Product</button>

    <script>
        // Initialize App Bridge
        const app = new JoonWebAppBridge({
            apiKey: '<?php echo $client_id; ?>',
            host: '<?php echo $host; ?>'
        });

        // Trigger native ProductPicker modal
        document.getElementById('pickerBtn').addEventListener('click', async () => {
            const Components = window.joonwebApp.actions.Components.create(window.joonwebApp);
            const selected = await Components.show('ProductPicker', 'select', {});
            console.log('Selected Product:', selected);
        });
    </script>
</body>
</html>
```

Read full component details in our [App Bridge Guide](/apps/app-bridge/app-bridge-overview).

##### Step 7: Deploy Your PHP App (joonweb app deploy)

When development is finished, publish a release snapshot:

```bash
joonweb app deploy
```

This packages your PHP app code and creates a draft build version in your Partner dashboard ready for live marketplace release.

##### Troubleshooting

### Port `11014` or `8000` Locked
If `joonweb app serve` errors with a port conflict:

```bash
joonweb refresh
```

This terminates leftover PHP or tunnel background processes.

##### What's Next?

- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Scope and proxy configuration.
- 🎨 **[Create Theme App Extensions](/apps/theme-app-extensions/create-theme-app-extensions)** — Add `.jw` storefront blocks.
- 🌉 **[App Bridge Component Guide](/apps/app-bridge/app-bridge-overview)** — Modal pickers & navigation.
- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — Token handshake reference.

---


### Go Live

#### Deploy Your App

##### Ready to Go Live

After finishing testing your app properly on a development site and following our quality guidelines, you are ready to deploy your app. Deploying your app will allow you to push it for production in JoonWeb.

JoonWeb CLI lets you use your local environment to run your app during development. However, to make your code available to actual merchants, you must move your code from your local development environment to a production hosting service, and push your configurations and extensions to JoonWeb.

##### Deployment Architecture: What Goes Where?

When deploying a JoonWeb app, your codebase is split between two destinations:

1. **Your Cloud/Hosting Service:** Your backend application code (Node.js, PHP, React frontend) must be uploaded to your preferred hosting provider (e.g., Vercel, AWS, Heroku, DigitalOcean).
2. **JoonWeb:** Your app configuration (`joonweb.app.json`) and any App Extensions (`extensions/` folder) are pushed directly to JoonWeb.

> **Important:** Do *not* upload your `extensions/` folder or your `joonweb.app.json` file to your hosting service. These are strictly managed by the JoonWeb CLI.

##### Step 1: Upload to your Hosting Service

The first step is to get your web app running on the internet.

1. Prepare your application for production (e.g., building assets, setting up production databases).
2. Deploy your application code (excluding extensions) to your hosting provider.
3. Note down the **production URL** assigned to your application (e.g., `https://my-joonweb-app.vercel.app`).

##### Step 2: Configure Production URLs

Before pushing to JoonWeb, you must tell JoonWeb where your app is hosted.

Open your local `joonweb.app.json` file and update the URLs to point to your new hosting service:

- **`app_url`**: The base URL of your hosted app (e.g., `https://mytestapp.joonweb.app`).
- **`redirect_uri`**: Your OAuth callback URLs (e.g., `https://mytestapp.joonweb.app/auth/callback`).

Ensure that you remove any `localhost` or tunneling (ngrok/Cloudflare) URLs from these fields.

##### Step 3: CLI Deployment

With your backend hosted and your `joonweb.app.json` updated, you are ready to push your configuration and extensions to JoonWeb.

Run the following command in your terminal:

```bash
joonweb app deploy
```

This command will:
- Update your app's URLs in the Partner Dashboard.
- Build and push your UI extensions to JoonWeb.
- Create a new version of your app.

[Learn more about the JoonWeb CLI](/apps/dev-tools)

##### What's Next?

Now that your app is deployed and running in production, the next step is to make it available to merchants.

Proceed to **[Publish to JoonWeb App Market](/apps/go-live/publish-to-market)** to learn about the review process and how to create your App Market listing.

---

#### Publish to JoonWeb App Market

##### Introduction to the App Market

With targeted recommendations and relevant categories, the **JoonWeb App Market** is the best place for merchants to find apps that they can use to build their business. 

When you’re ready to distribute your app, you must submit it to the App Approval team to ensure it meets all JoonWeb quality and security requirements.

##### Prerequisites

Before you begin the submission process, ensure you have:

- Thoroughly tested your app on a development site.
- Reviewed the App Market Review Guidelines.
- Created a comprehensive Privacy Policy for your app.
- Prepared testing instructions and dummy credentials for the JoonWeb review team.

##### Accessing the App Listing Form

To submit your app:

1. Log in to your **JoonWeb Partner Dashboard**.
2. Select your app.
3. Navigate to **Distribution Channel** and select **Public**.
4. You will be presented with the **App Publishing Console**.

##### App Listing Form Requirements

You will need to provide the following information in the App Publishing Console:

### 1. Core Details
- **App Name:** A unique, catchy name for your app (Max 30 characters).
- **Short Description (Tagline):** A one-sentence summary of what your app does (Max 60 characters).
- **App Icon:** A high-quality logo representing your app.
- **Category:** Select the primary category where merchants will find your app (e.g., Marketing, Store Design).

### 2. Developer & Emergency Information
- **Developer Email & Website:** Publicly visible information for merchant support.
- **Emergency Contact:** Internal contact details (Email/Phone) used by JoonWeb operations in case of critical app downtime.

### 3. Graphics & Full Description
- **Media:** Upload screenshots (images) or provide YouTube video URLs demonstrating your app in action.
- **Full Description:** A detailed explanation of your app's benefits, how it works, and why merchants need it.
- **Key Features:** Specific feature highlights. You can attach mini-icons to each feature for visual appeal.

### 4. Links & Reviewer Info
- **Mandatory Links:** Support URL and Privacy Policy URL.
- **Optional Links:** Terms & Conditions, and a Demo Store URL.
- **Testing Instructions:** Step-by-step instructions on how to test your app, including any required dummy accounts or passwords. This is strictly for the JoonWeb review team.

##### Submit for Review

Once you have filled out all required fields, you can save your progress as a draft. When you are fully confident that your app is ready, click **Submit for Review**.

The JoonWeb App Approval team will review your app and communicate any required changes.

##### What's Next?

While your app is under review, you should finalize your monetization plan. Proceed to **[Pricing Strategy](/apps/go-live/pricing-strategy)** to learn how to bill merchants for your app.

---

#### Pricing Strategy

##### JoonWeb App Pricing

Use JoonWeb App Pricing to define recurring subscriptions or one-time charges for your app. JoonWeb hosts the pricing plan selection page, bills merchants, and handles trials, upgrades, and downgrades, meaning you don't need to build or maintain complex billing logic yourself.

##### Pricing Models

When submitting your app via the App Publishing Console, you must define your pricing model:

- **Free to install:** The app is completely free, or acts as a companion to an external paid service.
- **Freemium:** Offers a free tier alongside paid upgrade plans.
- **Paid apps only:** Requires a subscription to use the app.

You can also offer a **Free Trial Duration (Days)** to let merchants test your app before they are billed.

##### Configuring Subscription Plans

If your app is Freemium or Paid, you will configure your plans during submission:
- **Plan Name:** e.g., 'Basic Plan', 'Pro Plan'.
- **Price:** The dollar amount billed to the merchant.
- **Billing Cycle:** Choose whether the merchant is billed Monthly or Yearly.

##### Implementing the Billing API

Once your plans are defined in your listing, you must implement the JoonWeb Billing API in your backend.

When a merchant installs your app or attempts to access premium features, your backend should:
1. Check their current active subscriptions using the Admin API.
2. If they need to pay, generate a subscription request via the Billing API.
3. Redirect the merchant to the JoonWeb-hosted payment approval screen using **App Bridge**.

##### App Bridge Integration

Using the `@joonweb/app-bridge-react` library, you can seamlessly navigate merchants to the billing approval screen without them leaving the JoonWeb Admin environment.

Ensure that you handle the auth callback after the merchant approves or declines the charge, and activate the subscription via the API before granting them access to premium features.

---


### Theme App extensions

#### Create theme app extensions

##### Overview

Theme App Extensions allow developers to build native, customizable Storefront UI components (Sections, Blocks, and Embed Scripts) using `.jw` template files and JSON rules.

This step-by-step guide explains how to generate, configure, and structure a Theme App Extension using the **JoonWeb CLI**.

> 🔗 **Prerequisite**: Make sure you have created your base app project first. If not, follow the [Create an App Guide](/apps/create/create-an-app).

##### Step 1: Open Terminal & Navigate to App Directory

Open your terminal or command prompt and navigate directly into your existing JoonWeb app folder (where your `joonweb.app.json` manifest file is located):

```bash
cd path/to/your-app
```

> ⚠️ **Directory Check**: The CLI checks if `joonweb.app.json` exists in your current folder. You cannot generate an extension outside a valid app directory.

##### Step 2: Run Extension Generation Command

Execute the extension generation command:

```bash
joonweb app generate extension
```

*(Alias: `joonweb app generate ext`)*

### Interactive CLI Prompts

1. **Select Extension Type**:  
   The CLI will display the extension menu. Select **Theme App Extension** (`theme_app_extension`).

   ```text
   🎨 Theme Extensions
   ──────────────────
   ❯ Theme App Extension - Customize store themes
   ```

2. **Enter Extension Name**:  
   Type your extension display name (e.g., `Smart Floating` or `Announcement Banner`).

```text
? Enter a name for your extension: Smart Floating
```

Once completed, the CLI registers the extension with your Partner account and scaffolds the extension directory.

##### Step 3: Extension Folder Structure

After running the generation command, a new `extensions/` directory is scaffolded inside your app folder:

```text
your-app/
├── extensions/
│   └── smart-floating/
│       ├── assets/                # CSS, JavaScript, images, and static files
│       ├── blocks/                # Storefront section and block .jw template files
│       ├── components/            # Reusable .jw code snippets
│       └── joonweb.extension.json # Extension manifest configuration
└── joonweb.app.json               # Main app manifest file
```

| Directory / File | Role |
| - | - |
| `blocks/` | Contains `.jw` UI component templates (e.g. `blocks/smart-float-block.jw`). |
| `components/` | Contains reusable `.jw` code snippets included inside blocks. |
| `assets/` | Static CSS stylesheets, JS scripts, and images. |
| `joonweb.extension.json` | Extension configuration file linking blocks to JoonWeb Site Builder. |

##### Step 4: Understand joonweb.extension.json Manifest

Inside your generated extension folder (`extensions/smart-floating/`), open `joonweb.extension.json`:

```json
{
  "name": "Smart Floating",
  "version": "1.0.0",
  "handle": "smart-floating",
  "type": "theme_app_extension",
  "extension_key": "",
  "blocks": [
    {
      "type": "app_sections",
      "name": "Great Float Sections",
      "target": "section",
      "src": "blocks/smart-float-block.jw"
    }
  ],
  "uid": "7e24ff92-9362-4765-8909-1db290511f"
}
```

### Manifest Fields Explained

- **`name`**: The human-readable extension title displayed in the JoonWeb Site Builder.
- **`handle`**: Unique slug identifier generated by the CLI (**DO NOT CHANGE**).
- **`type`**: Fixed identifier set to `theme_app_extension` (**DO NOT CHANGE**).
- **`extension_key`**: Platform registration key.
- **`uid`**: Unique UUID linking the extension to your app (**DO NOT CHANGE OR REGISTRATION BREAKS**).
- **`blocks`**: Array defining the UI components available in Site Builder.

### Block Properties & Types

| Property | Values | Description |
| - | - | - |
| **`type`** | `app_sections` | Standalone section layout that merchants can add anywhere on a page. |
| | `app_blocks` | Component block placed inside existing theme sections (e.g. under product price). |
| | `app_embed` | Script or floating overlay injected globally. |
| **`target`** | `section` | Target location for layout sections or blocks. |
| | `head` / `compliance_head` / `body` | Injection targets for `app_embed` floating scripts or banners. |
| **`src`** | `blocks/filename.jw` | Relative file path to your `.jw` template file. |
| **`name`** | `string` | Display name of the block shown in Site Builder. |

> 🚨 **Critical Rule**: Do **not** copy extension folders from other app repositories. Copying folders corrupts the extension `uid` and causes deployment failures.

##### 📁 The .jw Template & Rules Anatomy

Every storefront component is authored inside a `.jw` file in the `blocks/` directory (e.g., `blocks/smart-float-block.jw`).

A `.jw` file combines HTML/CSS markup with a `{% rules %}` JSON schema that generates setting controls in the Site Builder:

```jw
<div class="smart-float-widget" style="background-color: {{ section.settings.bg_color }}; padding: {{ section.settings.padding }}px;">
    <h3 style="color: {{ section.settings.text_color }};">{{ section.settings.heading }}</h3>
</div>

{% rules %}
{
  "name": "Smart Float Section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading Text",
      "default": "Special Offer!"
    },
    {
      "type": "color",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#4f46e5"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text Color",
      "default": "#ffffff"
    },
    {
      "type": "range",
      "id": "padding",
      "label": "Padding (px)",
      "min": 10,
      "max": 50,
      "step": 5,
      "default": 20
    }
  ]
}
{% endrules %}
```

##### Step 5: Preview & Deploy Your Extension

To test your extension live in your Development Store, run:

```bash
joonweb app serve
```

Open your Development Store's **Site Builder**, click **Add Section** -> **Apps**, and select your extension.

When ready to publish, deploy your snapshot:

```bash
joonweb app deploy
```

##### What's Next?

- ⚙️ **[Configure Theme App Extensions](/apps/theme-app-extensions/configure-theme-app-extensions)** — Learn Deep Linking and Asset API installation checks.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Back to core app creation guide.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/joonweb-cli/configuration/app-manifest)** — Configure app webhooks & proxy.
- 🛠️ **[JoonWeb CLI Command Reference](/joonweb-cli/commands/command-reference)** — Complete CLI command options.

---

#### Configure theme app extensions

##### Extension Manifest (joonweb.extension.json)

Once created, your extension is configured via `joonweb.extension.json`:

```json
{
  "name": "MY Extension",
  "handle": "smart-floating",
  "type": "theme_app_extension",
  "extension_key": "",
  "blocks": [
    {
      "type": "app_sections",
      "name": "My Section",
      "target": "section",
      "src": "blocks/your-section_or_block.jw"
    }
  ],
  "uid": "7e24ff92-9362-4765-8909-bdb290511f"
}
```

### Field Rules:
- **`name`**: Extension display name in builder.
- **`handle`**: Internal handle (**DO NOT CHANGE**).
- **`type`**: Extension type `theme_app_extension` (**DO NOT CHANGE**).
- **`extension_key`**: System registration key.
- **`blocks.type`**: Use `app_sections` or `app_blocks` for sections, and `app_embed` for scripts/overlays.
- **`blocks.target`**: Use `section` for sections; use `head`, `compliance_head`, or `body` for embeds.
- **`uid`**: Unique identifier (**DO NOT CHANGE OR IT WILL BREAK**).

##### Deep Linking Specification

Post-installation, your app can deep-link merchants directly into the Site Builder to activate embeds or add section blocks automatically.

### 1. For Embed Extensions (`app_embed`)
```text
https://accounts.joonweb.com/site/builder/?activate_extension={extension_uid}/{block_handle}
```
* **Example**: `https://accounts.joonweb.com/site/builder/?activate_extension=7720ed2b-c190-44ba-bf1b-f1b096e1e587/lastSold-section-block`
* **Parameters**:
  * `extension_uid`: Extension UID string from `joonweb.extension.json`.
  * `block_handle`: Filename of the block file (without `.jw`).

### 2. For Section Extensions (`app_sections`)
```text
https://accounts.joonweb.com/site/builder/?add_extension={ext_uuid}/{ext_block}&target_page=collections
```
* **Example**: `https://accounts.joonweb.com/site/builder/?add_extension=7e24ff92-9362-4765-8909-bdb2905f001f/reels-section-block&target_page=products`
* **Parameters**:
  * `add_extension`: `{extension_uid}/{block_handle}`
  * `target_page`: Target page URL or ID (`home`, `products`, `collections`, `login`, `signup`). Leave blank for homepage.

##### Detecting If Embedded App Is Installed

Fetch active theme configuration via the Admin API to check if your app or block is installed and enabled:

**Endpoint**:
```http
GET https://{yoursite}.myjoonweb.com/api/admin/26.0/themes/current/assets/file?key=theme_config.json
```

**JavaScript Check Function**:
```javascript
const res = await fetch(url, { headers: { 'Authorization': `Bearer ${apiToken}` } });
const data = await res.json();
const config = JSON.parse(data.asset.content);
const blocks = config.blocks || {};

let isInstalled = false;
let isEnabled = false;

// Method A: Check via App Handle
const APP_HANDLE = "my-app";
for (const id in blocks) {
  if (blocks[id].type === "apps" && blocks[id].src.includes(`/apps/${APP_HANDLE}/`)) {
    isInstalled = true;
    isEnabled = blocks[id].enabled === true;
    break;
  }
}

// Method B: Check via Block Name
const block_name = "my-block_file";
for (const id in blocks) {
  if (blocks[id].type === "apps" && blocks[id].src.includes(`/blocks/${block_name}/`)) {
    isInstalled = true;
    isEnabled = blocks[id].enabled === true;
    break;
  }
}

console.log({ isInstalled, isEnabled });
```

##### What's Next?

- 🚀 **[Create Theme App Extensions Guide](/apps/theme-app-extensions/create-theme-app-extensions)** — `.jw` template anatomy & input rules.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/joonweb-cli/configuration/app-manifest)** — Configure webhooks & app proxy.
- 🛠️ **[JoonWeb CLI Command Reference](/joonweb-cli/commands/command-reference)** — Complete CLI options.

---


### App Bridge

#### App Bridge Overview & Component Endpoints

##### Overview of JoonWeb App Bridge

App Bridge establishes a secure, real-time communication channel between your embedded app loaded inside the JoonWeb iframe and the parent JoonWeb Admin dashboard.

It allows embedded apps to render native title bars, trigger native modal pickers (ProductPicker, LinkManager, FileManager), initiate billing charges, and manage client-side SPA routing without causing full browser hard reloads.

##### App Bridge Initialization

Include the App Bridge script in your `<head>` or before the closing `</body>` tag:

```html
<script src="https://apps.joonweb.com/app-bridge.js"></script>
```

Initialize App Bridge on DOM load:

```javascript
document.addEventListener('DOMContentLoaded', () => {
    if (typeof window.JoonWebAppBridge === 'undefined' || window.joonwebApp) {
        return;
    }
    
    // Initialize App Bridge
    window.joonwebApp = new JoonWebAppBridge({
        apiKey: 'jw_client_xxxxxxxx',
        host: 'encoded_host_from_url',
        site: 'yoursite.myjoonweb.com'
    });
    
    console.log('JoonWeb App Bridge initialized');
    
    // Set default TitleBar
    const { TitleBar } = window.joonwebApp.actions || {};
    if (TitleBar) {
        TitleBar.create(window.joonwebApp, {
            title: 'My Custom App'
        });
    }
});
```

##### Native UI Components & Modals

App Bridge components allow your app to open native JoonWeb Admin modal dialogs:

| Component | Purpose |
| - | - |
| **`ProductPicker`** | Modal for selecting store products |
| **`CollectionSelector`** | Modal for selecting store collections |
| **`LinkManager`** | Pick URLs, handles, and labels for pages, products, posts, collections, or custom web links |
| **`FileManager`** | Browse, upload, and select media files (images, documents) from JoonWeb media library |
| **`VideoManager`** | Embed and validate YouTube and Vimeo video URLs |
| **`RequestCharge`** | Initiates merchant billing charge checkout modal using a `charge_id` |
| **`PostSelector`** | Modal for selecting blog articles |
| **`BlogCategorySelector`** | Modal for selecting blog categories |

##### ProductPicker Usage Example

```javascript
const btn = document.querySelector('#btn-select-product');
btn.addEventListener('click', async (e) => {
    e.preventDefault();
    if (window.joonwebApp.actions.Components) {
        const ProductPicker = window.joonwebApp.actions.Components.create(window.joonwebApp);
        const selectedProduct = await ProductPicker.show('ProductPicker');
        console.log('Selected Product:', selectedProduct);
    }
});
```

##### LinkManager Component (Add & Update Modes)

The `LinkManager` component opens a modal allowing merchants to pick store links:

### 1. Add Mode
```javascript
const Components = window.joonwebApp.actions.Components.create(window.joonwebApp);
const linkData = await Components.show('LinkManager', 'add', {}, {
    options: ['pages', 'product', 'collection', 'web'],
    hideLabel: false,
    advance: true
});
console.log(linkData);
```

### 2. Update Mode
Pass the base64 `options` string previously returned:
```javascript
const existingLink = {
    type: 'web',
    title: 'JoonWeb Partners',
    options: 'BASE64_ENCODED_STRING'
};
const updatedData = await Components.show('LinkManager', 'update', existingLink, { advance: true });
```

### Returned Data Object
```json
{
  "site_url": "https://store.myjoonweb.com",
  "label": "Classic Shoes",
  "handle": "classic-shoes",
  "full_url": "https://store.myjoonweb.com/products/classic-shoes",
  "type": "product",
  "url": "/products/classic-shoes",
  "options": "BASE64_ENCODED_STRING"
}
```

##### FileManager Component

```javascript
const fileData = await Components.show('FileManager', {
    mode: 'single',             // 'single' or 'multiple'
    activeTab: 'images',        // 'images' or 'documents'
    allowedTabs: ['images', 'documents'],
    zone: 'products'
});
console.log('Selected Asset:', fileData);
```

##### RequestCharge Billing Modal

To initiate a billing flow, retrieve a `charge_id` from the Admin API (`POST /api/admin/26.0/create_app_billing`) and trigger the billing modal:

```javascript
const charge_id = 'jw_charge_xxxxxxxx'; // From Admin Billing API
const Charge = window.joonwebApp.actions.Components.create(window.joonwebApp);
await Charge.show('RequestCharge', charge_id);
```

##### Native Navigation & Client-Side SPA Routing

Create native navigation menus in the JoonWeb Admin header bar:

```javascript
if (window.joonwebApp.actions.Navigation) {
    const menu = window.joonwebApp.actions.Navigation.create(window.joonwebApp);
    menu.setMenu({
        items: [
            { label: 'Home', destination: '/' },
            { label: 'Settings', destination: '/settings' }
        ]
    });
}
```

### Handling SPA Internal Navigation (React Router)
Intercept the `joonweb:navigation:menu` event to prevent hard browser reloads:

```javascript
window.addEventListener('joonweb:navigation:menu', (event) => {
    event.preventDefault(); // Prevent browser hard reload
    const { destination } = event.detail;
    navigate(destination);  // Use react-router-dom navigate()
});
```

##### React & Node SDK Packages

### React Integration (`@joonweb/app-bridge-react`)
Wrap your app root with `<JoonwebProvider>` and use `<AppBridgeLink>`:

```jsx
import { JoonwebProvider, useAppBridge, AppBridgeLink } from '@joonweb/app-bridge-react';

function App() {
  return (
    <JoonwebProvider apiKey="jw_client_xxxxxxxx" host={host}>
      <AppBridgeLink to="/settings">Settings</AppBridgeLink>
    </JoonwebProvider>
  );
}
```

### Node.js Express Integration (`@joonweb/app-bridge-node`)
Protect Express API routes using `requireAppBridgeSession()` middleware:

```javascript
const { requireAppBridgeSession } = require('@joonweb/app-bridge-node');

app.get('/api/products', requireAppBridgeSession({ clientSecret: process.env.CLIENT_SECRET }), (req, res) => {
    res.json({ success: true });
});
```

##### What's Next?

- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Step-by-step app initialization tutorial.
- ⚙️ **[App Manifest Reference](/apps/dev-tools/app-manifest)** — Manifest fields, proxy, and webhooks.
- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange reference.

---


### Dev Tools & CLI

#### JoonWeb CLI Command Endpoints

##### Overview of JoonWeb CLI Commands

The **JoonWeb CLI** (`joonweb`) provides commands for scaffolding, running local servers, managing theme app extensions, and deploying app release versions.

### Global Options
| Flag | Description |
| - | - |
| `-v, -V, --version` | Output current CLI version |
| `-d, --debug` | Enable verbose debug output (`DEBUG=true`) |

##### App Command Group (`joonweb app ...`)

### 1. `joonweb app init` (Create App)
* **Alias**: `joonweb app create`
* **Description**: Scaffolds a new JoonWeb app project.

```bash
joonweb app init
```

* **Guided Steps**: Prompts for Partner login, App Name, and Tech Stack selection (Node+React, Express, PHP). Scaffolds project folder containing `joonweb.app.json`.

---

### 2. `joonweb app serve` (Development Server)
* **Alias**: `joonweb app dev`
* **Description**: Starts local development server with auto-tunneling and hot reloading.

```bash
joonweb app serve [options]
```

#### Options & Flags:
| Flag | Description | Default |
| - | - | - |
| `--port <port>` | Specify local server port number | `11014` |
| `--no-tunnel` | Disable automatic HTTPS tunnel creation | `false` |
| `--no-open` | Disable browser auto-opening for OAuth consent | `false` |

---

### 3. `joonweb refresh` (Port Conflict Fix)
* **Description**: Clears background server locks and resets port `11014`.

```bash
joonweb refresh
```

> 💡 **Solution**: If you encounter `ERR: already port open`, run `joonweb refresh` before re-running `joonweb app serve`.

---

### 4. `joonweb app regenerate` (Reload Templates)
* **Aliases**: `joonweb app reset`, `joonweb app reload`
* **Description**: Reloads all project template files from GitHub while preserving your `joonweb.app.json` config.

```bash
joonweb app regenerate
```

---

### 5. `joonweb app generate extension` (App Extensions)
* **Alias**: `joonweb app generate ext`
* **Description**: Generates a Theme App Extension directory (`extensions/my-extension/`).

```bash
joonweb app generate extension
```

---

### 6. `joonweb app deploy` (Release Version)
* **Alias**: `joonweb app push`
* **Description**: Deploys an app snapshot to the JoonWeb platform.

```bash
joonweb app deploy [options]
```

#### Options & Flags:
| Flag | Description | Default |
| - | - | - |
| `--env <env>` | Target deployment environment | `default` |
| `--no-release` | Skip creating a new live release version | `false` |

##### Account & Maintenance Commands

### `joonweb login` 
Authenticates CLI with your Partner Account.
```bash
joonweb login [--shop <domain>]
```

### `joonweb whoami` 
Displays current active login status.
```bash
joonweb whoami
```

### `joonweb logout` 
Logs out and clears local credentials.
```bash
joonweb logout
```

### `joonweb update` (Alias: `upgrade`)
Updates CLI to latest version.
```bash
joonweb update
```

### `joonweb uninstall` (Alias: `remove`)
Uninstalls CLI completely.
```bash
joonweb uninstall
```

##### What's Next?

- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Complete schema specifications.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app development tutorial.
- 🎨 **[Create Theme App Extensions](/apps/theme-app-extensions/create-theme-app-extensions)** — Build storefront UI blocks.

---

#### App Manifest (joonweb.app.json)

##### Overview

The `joonweb.app.json` file is the central manifest for your JoonWeb application. It defines your app ID, OAuth credentials, API access scopes, proxy settings, webhooks, and framework template metadata.

> ⚠️ **CRITICAL WARNING**: `joonweb.app.json` is generated by [`joonweb app init`](/apps/dev-tools/cli-commands#section-220). **It must NOT be deleted or replaced at any cost**, as it links your local project to your JoonWeb Technology Partner account.

##### Official joonweb.app.json Schema

Below is the complete official JSON structure of `joonweb.app.json`:

```json
{
  "appId": "8c21b0e81773747658577",
  "name": "mytestapp",
  "client_id": "0b990a0bb51fb125",
  "client_secret": "b90984d32211c49f8b94a3e04eb588f3be42",
  "app_url": "https://mytestapp.joonweb.app",
  "redirect_uri": "https://mytestapp.joonweb.app/auth/callback",
  "scopes": "read_products,write_products",
  "proxy": {
    "url": "https://mytestapp.joonweb.app/proxy",
    "status": "active"
  },
  "webhooks": [
    {
      "event": "products/create",
      "address": "https://mytestapp.joonweb.app/webhooks/products_create",
      "format": "json"
    }
  ],
  "template": "php",
  "embedded": true,
  "platform": "ecommerce",
  "version": "1.0.0"
}
```

##### Manifest Parameter Reference

| Property | Type | Description |
| - | - | - |
| `appId` | `string` | Unique application identifier registered on JoonWeb. |
| `name` | `string` | Name of your application. |
| `client_id` | `string` | Public OAuth Client ID used by App Bridge for iframe authentication. |
| `client_secret` | `string` | Private secret key used for server-side HMAC session verification and token exchange. |
| `app_url` | `string` | Main HTTPS application URL where your web server is hosted (updated automatically by `joonweb app serve`). |
| `redirect_uri` | `string` | OAuth authorization callback URL. |
| `scopes` | `string` | Comma-separated list of requested API permissions (e.g. `"read_products,write_products"`). |
| `proxy` | `object` | Storefront App Proxy configuration containing `url` and `status` (`"active"`). |
| `webhooks` | `array` | List of webhook event subscriptions containing `event`, `address`, and `format` (`"json"`). |
| `template` | `string` | Project framework template (e.g. `"php"`, `"node"`, `"react"`). |
| `embedded` | `boolean` | `true` if app runs embedded inside the JoonWeb Admin iframe. |
| `platform` | `string` | Target platform capability (`"ecommerce"`). |
| `version` | `string` | App version string (e.g. `"1.0.0"`). |

##### What's Next?

- 🚀 **[Run `joonweb app serve`](/apps/dev-tools/cli-commands#2-joonweb-app-serve-development-server)** — Start dev server with tunnel.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.
- 🎨 **[Create Theme App Extensions](/apps/theme-app-extensions/create-theme-app-extensions)** — Build storefront UI blocks.

---


## Themes

### Getting Started

#### Theme Architecture & Directory Structure

##### Overview & Theme Philosophy

A **JoonWeb Theme** is a modular storefront design package that controls the visual presentation, layout, typography, colors, and dynamic interactive behavior of a merchant's store.

JoonWeb themes utilize native `.jw` templates and JSON schema rules to bridge the gap between frontend developers and store merchants:
- **Full Creative Freedom**: Developers build responsive layouts using Bootstrap 5.3, custom scoped CSS, vanilla JavaScript, and jQuery.
- **Visual Customization for Merchants**: Every `.jw` section exposes settings, image pickers, color controls, and block managers in the JoonWeb Site Builder without touching code.
- **High Performance**: Assets are served directly via high-speed CDN, and `.jw` templates are compiled dynamically with zero client-side framework bloat.

##### Official Theme Directory Structure

Every JoonWeb theme follows a standardized file and folder hierarchy:

```text
your-theme/
├── layout.jw                  # Master HTML shell & global document wrapper
├── theme_config.json          # Theme metadata, color palette & typography presets
├── theme_structure.json       # Page templates layout & default section hierarchy
├── sections/                  # Dynamic storefront sections (.jw)
│   ├── header.jw              # Store navigation bar & announcements
│   ├── hero.jw                # Hero banners & sliders
│   ├── product-grid.jw        # Product catalogue listings
│   ├── cart.jw                # Shopping cart page & slide-over drawer
│   ├── card-slider.jw         # Featured collection carousel
│   ├── blog.jw                # Article feeds & news
│   ├── breadcrumb.jw          # Hierarchical page navigation
│   └── footer.jw              # Multi-column footer & copyright
├── components/                # Reusable template components (.jw)
│   ├── pagination.jw          # Reusable page navigation
│   ├── product-list.jw        # Product item card snippet
│   ├── product-filters.jw     # Faceted sidebar collection filters
│   ├── product-review.jw      # Customer reviews & ratings
│   └── wishlist.jw            # Wishlist trigger & counter
├── blocks/                    # Atomic nested block components (.jw)
│   ├── group.jw               # Layout wrapper & flex container block
│   └── myheading.jw           # Configurable typography block
├── assets/                    # Static theme assets (CDN-hosted)
│   ├── style.css              # Custom theme stylesheet
│   ├── index.js               # Theme interaction JavaScript
│   ├── apiClient.js           # Ajax API client helper
│   ├── slick.min.js           # Slider library
│   ├── aos.css                # Scroll animations CSS
│   └── fonts/                 # Custom web fonts (.ttf, .woff2)
└── apps/                      # Installed Theme App Extensions
    └── {app_id}/              # App-injected blocks and embeds (.jw & .json)
```

### Directory & File Roles

| Folder / File | Purpose |
|---|---|
| `layout.jw` | The root master layout wrapping every page (`<head>`, meta tags, header/footer inclusions, and main content outlet). |
| `theme_config.json` | Stores global theme metadata (`name`, `type`, `engine`), default typography, color palette, and presets. |
| `theme_structure.json` | Defines default section order and presets across templates (`home`, `product`, `collection`, `cart`). |
| `sections/` | Modular `.jw` sections that merchants can add, reorder, remove, and customize in the Site Builder. |
| `components/` | Reusable `.jw` snippets imported into sections (e.g. `product-list.jw`, `pagination.jw`). |
| `blocks/` | Atomic block elements that can be nested inside sections via the Site Builder. |
| `assets/` | Static CSS, JS, fonts, and images uploaded directly to CDN storage. |
| `apps/` | Dedicated directory where JoonWeb App Extensions automatically place app blocks and theme embeds. |

> 🔒 **Ignored Directories**: The folders `trash/`, `cache/`, and `rules/` are internal system folders. Theme developers and AI tools must never create or modify files inside these paths.

##### theme_config.json Architecture & Rules

The `theme_config.json` file controls the global design tokens, typography, and color schemes across the entire storefront.

### Strict Schema Structure

```json
{
  "info": {
    "name": "Sporty Store",
    "type": "store",
    "author": "JoonWeb Design Team",
    "engine": 2
  },
  "default": {
    "fontStyle": {
      "heading": { "family": "Inter", "weight": "700" },
      "body": { "family": "Inter", "weight": "400" }
    },
    "colors": {
      "color1": "#0f172a",
      "color2": "#1e293b",
      "color3": "#2563eb",
      "color4": "#f8fafc",
      "color5": "#ffffff",
      "color6": "#64748b"
    }
  },
  "presets": [
    {
      "label": "Ocean Modern",
      "set": {
        "fontUnit": "px",
        "fontStyle": {
          "heading": { "family": "Outfit", "weight": "700" },
          "body": { "family": "Plus Jakarta Sans", "weight": "400" }
        },
        "colors": {
          "color1": "#0c4a6e",
          "color2": "#0284c7",
          "color3": "#38bdf8",
          "color4": "#f0f9ff",
          "color5": "#ffffff",
          "color6": "#475569"
        }
      }
    }
  ]
}
```

### Key Architectural Guidelines
1. **Mandatory Root Keys**:
   - `"info"`: Contains `"name"`, `"type"` (must strictly be either `"site"` or `"store"`), `"author"`, and `"engine"` (`1` or `2`, where `2` is latest).
   - `"default"`: Contains default typography (`fontStyle`) and base color palette (`colors`).
   - `"presets"`: Array of merchant-selectable color combinations and font pairings.
2. **Protected Keys**:
   - `"blocks"` and `"settings"` are protected system structures. Custom themes must not inject ad-hoc objects into these keys.
3. **Pure Valid JSON**: No trailing commas or unquoted keys are allowed; `theme_config.json` is validated upon every upload.

---


### Core Utilities

#### Typography & Background Color Utility Classes

##### Theme Typography Scale (.fontStyle1 to .fontStyle9)

JoonWeb themes utilize a standardized typography hierarchy ranging from `.fontStyle1` down to `.fontStyle9`. These classes automatically inherit font families, letter spacing, and line heights defined in `theme_config.json`.

| Class | Hierarchy Level | Primary Use Case |
|---|---|---|
| `.fontStyle1` | Display / Hero Title | Storefront hero headers & main banner text |
| `.fontStyle2` | Heading 2 | Section main titles & prominent modal headers |
| `.fontStyle3` | Heading 3 | Collection headers, card titles & product names |
| `.fontStyle4` | Heading 4 | Widget titles, sidebar group headers |
| `.fontStyle5` | Heading 5 | Sub-headings, feature highlights, card labels |
| `.fontStyle6` | Heading 6 | Product tags, badge labels & small headings |
| `.fontStyle7` | Body Text / Paragraph | Default body copy, descriptions, article text |
| `.fontStyle8` | Secondary Text | Helper text, breadcrumb links, pricing subtext |
| `.fontStyle9` | Fine Print / Footnote | Copyright text, legal disclaimers, micro metadata |

### Typography Usage Example

```jw
<div class="hero-content">
  <h1 class="fontStyle1">{{ section.settings.title }}</h1>
  <p class="fontStyle7 text-muted">{{ section.settings.description }}</p>
  <span class="fontStyle9">Free shipping on orders over {{ site.currency }}999</span>
</div>
```

##### Dynamic Font Customization via Property Object

In addition to static typography utility classes, JoonWeb sections can bind individual headings directly to visual typography controls in the Site Builder using the global `Property` object:

```jw
<style>
  #{{ section.id }} .theme-title .jwset {
    font-size: {{ Property.title.style['size'] | default(32) }}px;
    font-family: {{ Property.title.style['family'] | default('Inter') }};
    font-weight: {{ Property.title.style['weight'] | default('700') }};
    line-height: {{ Property.title.style['height'] | default('1.2') }};
    letter-spacing: {{ Property.title.style['spacing'] | default('0') }};
  }
</style>

<div class="theme-title">
  <span class="jwset">{{ section.settings.title }}</span>
</div>
```

This pattern gives merchants granular control over font sizes, letter spacing, and weights on both desktop and mobile screens.

##### Global Theme Colors & Background Classes (.background1 to .background6)

Every JoonWeb theme defines 6 global CSS color tokens in `theme_config.json` (`--color1` through `--color6`). 

Storefront sections use 6 harmonious background utility classes (`.background1` to `.background6`) that automatically map background colors with contrast-optimized text and border colors:

| Class | Background Token | Text Color Token | Border Color Token | Typical Application |
|---|---|---|---|---|
| `.background1` | `var(--color1)` | `var(--color5)` | `var(--border1)` | Dark primary header / hero / dark mode |
| `.background2` | `var(--color2)` | `var(--color6)` | `var(--border1)` | Secondary surface / widget cards |
| `.background3` | `var(--color3)` | `var(--color5)` | `var(--border1)` | Accent callout / active state background |
| `.background4` | `var(--color4)` | `var(--color6)` | `var(--border1)` | Subtle light container / muted banner |
| `.background5` | `var(--color5)` | `var(--color6)` | `var(--border1)` | Crisp white / default light background |
| `.background6` | `var(--color6)` | `var(--color5)` | `var(--border1)` | Deep charcoal / dark footer background |

### Dynamic Color Palette Binding

```jw
{# Section wrapper uses merchant's selected color scheme #}
<section class="section-padding {{ section.colors ? section.colors : 'background5' }}" id="{{ section.id }}">
  <div class="container">
    {# Inner card uses secondary scheme #}
    <div class="card p-4 {{ section.colors2 ? section.colors2 : 'background2' }}">
      <h3 class="fontStyle3">{{ block.settings.title }}</h3>
    </div>
  </div>
</section>
```

##### Button Styles & Dynamic Border Radius

### Button Utility Classes
JoonWeb themes standardize button dimensions and hover transitions using `.btns`:

- `.btns`: Base button styling with smooth transition and cursor pointer.
- `.btns-sm`: Small compact button (e.g. quick buy or tag triggers).
- `.btns-md`: Standard medium button (default for add-to-cart).
- `.btns-lg`: Large call-to-action button (hero sliders).
- `.btns-xlg`: Extra-large prominent action button.

```jw
{% set button_size_typ = {
  "btns-sm": "btns-sm",
  "btns-md": "btns-md",
  "btns-lg": "btns-lg",
  "btns-xlg": "btns-xlg"
} %}
{% set button_typ = button_size_typ[section.desktop.buttonSize] ?? 'btns-md' %}

<a href="{{ section.settings.link.url }}" class="btns border-radius {{ button_typ }} {{ section.colors3 ? section.colors3 : 'background3' }}">
  <span>{{ section.settings.link.label | default('Shop Now') }}</span>
</a>
```

### Dynamic Border Radius
Expose slider controls in `{% rules %}` and apply dynamic border radius to cards and buttons:

```css
<style>
  {% if section.desktop.borderRadius %}
    #{{ section.id }} .border-radius {
      border-radius: {{ section.desktop.borderRadius }}px;
    }
  {% endif %}
</style>
```

---


### Section & Block System

#### Section Anatomy & Block System

##### Anatomy of a .jw Section File

A `.jw` section is a self-contained storefront building block that combines **dynamic template markup**, **scoped styling**, **client-side JavaScript**, and an embedded **`{% rules %}` JSON schema**.

### Production Template Anatomy (Based on cart.jw)

```jw
{# 1. DYNAMIC CONFIGURATION & VARIABLE MAPPING #}
{% set button_size_typ = {
  "btns-sm": "btns-sm",
  "btns-md": "btns-md",
  "btns-lg": "btns-lg",
  "btns-xlg": "btns-xlg"
} %}
{% set button_typ = button_size_typ[section.desktop.buttonSize] ?? 'btns-md' %}

{# 2. SCOPED STYLES (Scoped with #{{ section.id }}) #}
<style>
  /* Border radius configuration */
  {% if section.desktop.borderRadius %}
    #{{ section.id }} .border-radius {
      border-radius: {{ section.desktop.borderRadius }}px;
    }
  {% endif %}

  /* Responsive section padding */
  {% if section.desktop.deskPaddingTop or section.desktop.deskPaddingBottom or section.mobile.deskPaddingTop or section.mobile.deskPaddingBottom %}
    #{{ section.id }} {
      padding-top: {{ section.mobile.deskPaddingTop | default(30) }}px;
      padding-bottom: {{ section.mobile.deskPaddingBottom | default(30) }}px;
    }
    @media screen and (min-width: 750px) {
      #{{ section.id }} {
        padding-top: {{ section.desktop.deskPaddingTop | default(60) }}px;
        padding-bottom: {{ section.desktop.deskPaddingBottom | default(60) }}px;
      }
    }
  {% endif %}

  /* Dynamic font styles from Property object */
  #{{ section.id }} .theme-title .jwset {
    font-size: {{ Property.title.style['size'] | default(28) }}px;
    font-family: {{ Property.title.style['family'] | default('Inter') }};
    font-weight: {{ Property.title.style['weight'] | default('700') }};
    line-height: {{ Property.title.style['height'] | default('1.2') }};
    letter-spacing: {{ Property.title.style['spacing'] | default('0') }};
  }
</style>

{# 3. SECTION MARKUP & STOREFRONT DATA BINDING #}
<section class="jw_section section-padding {{ section.colors ? section.colors : 'background5' }}" id="{{ section.id }}">
  <div class="{{ section.desktop.sectionWidth ? section.desktop.sectionWidth : 'container' }}">
    {% if title %}
      <div class="fontStyle3 theme-title mb-4">
        <span class="jwset">{{ title }}</span>
      </div>
    {% endif %}

    {# RENDER BLOCKS OR CUSTOM CONTENT #}
    {% if section.blocks is defined and section.blocks | length > 0 %}
      <div class="row g-4">
        {% for block in section.blocks %}
          <div class="col-md-4" {{ jw_attributes(block) }}>
            {% switch block.type %}
              {% case "feature_card" %}
                <div class="card p-4 border-radius {{ section.colors2 ? section.colors2 : 'background5' }}">
                  {% if block.settings.icon %}
                    <img src="{{ block.settings.icon | asset_url }}" class="mb-3" style="width: 48px;">
                  {% endif %}
                  <h4 class="fontStyle5">{{ block.settings.title }}</h4>
                  <p class="fontStyle7 text-muted">{{ block.settings.description }}</p>
                </div>
              {% default %}
                {{ render_block(block) }}
            {% endswitch %}
          </div>
        {% endfor %}
      </div>
    {% endif %}
  </div>
</section>

{# 4. SCOPED JAVASCRIPT #}
<script>
$(document).ready(function() {
  $('#{{ section.id }} .jw_action_btn').on('click', function() {
    console.log('Action triggered in section {{ section.id }}');
  });
});
</script>

{# 5. EMBEDDED RULES SCHEMA #}
{% rules %}
{
  "name": "Feature Highlights",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Section Heading",
      "default": "Why Choose Us"
    },
    {
      "type": "range",
      "id": "borderRadius",
      "label": "Card Border Radius",
      "min": 0,
      "max": 30,
      "step": 2,
      "unit": "px",
      "default": 12
    }
  ],
  "blocks": [
    {
      "type": "feature_card",
      "name": "Feature Card",
      "settings": [
        { "type": "image_picker", "id": "icon", "label": "Icon Image" },
        { "type": "text", "id": "title", "label": "Title", "default": "Fast Shipping" },
        { "type": "textarea", "id": "description", "label": "Description", "default": "Delivery within 48 hours." }
      ]
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [
    {
      "name": "Feature Highlights",
      "category": "Promotional"
    }
  ]
}
{% endrules %}
```

##### Critical Syntax Invariant: The {# Spacing Rule

In JW template syntax, template comments start with `{#` and end with `#}`.

### ⚠️ The CSS Collision Pitfall
In CSS `<style>` blocks or inline styles, if an opening brace `{` is followed immediately by an ID selector `#` without a whitespace character, the JW Engine will parse it as the start of a comment!

```css
/* ❌ CRITICAL ERROR - Causes "Unclosed comment" fatal parse error: */
@media (max-width: 768px) {#{{ section.id }} { display: block; }}
.menu {#nav { display: flex; }}

/* ✅ CORRECT - Always place a space or newline after { before #: */
@media (max-width: 768px) { #{{ section.id }} { display: block; } }
.menu { #nav { display: flex; } }
```

> **Golden Rule**: Always put a whitespace between `{` and `#` when writing scoped section CSS.

##### Core Section Objects & Functions

Every `.jw` section has access to global and section-level context variables:

| Object / Function | Description | Example |
|---|---|---|
| `section.id` | Unique alphanumeric identifier for this section instance. | `#{{ section.id }}` |
| `section.settings` | Values configured by the merchant in `{% rules %}` settings. | `{{ section.settings.title }}` |
| `section.desktop` | Desktop design settings (`deskPaddingTop`, `borderRadius`, `sectionWidth`). | `{{ section.desktop.deskPaddingTop }}` |
| `section.mobile` | Mobile design settings (`deskPaddingTop`, `deskPaddingBottom`). | `{{ section.mobile.deskPaddingTop }}` |
| `section.colors` | Active color scheme class (`background1` to `background6`). | `class="{{ section.colors }}"` |
| `Property.*.style` | Font properties object (`size`, `family`, `weight`, `height`, `spacing`). | `{{ Property.title.style['size'] }}px` |
| `cart` | Global cart object (`cart.items`, `cart.subtotal`, `cart.total`, `cart.discount`). | `{% if cart.items %}` |
| `site.currency` | Merchant's active store currency symbol (e.g. `₹`, `$`, `€`). | `{{ site.currency }}{{ item.sale_price }}` |
| `root.url` | Store root URL for internal linking. | `<a href="{{ root.url }}/collections">` |
| `jw_attributes(block)` | Emits selection attributes required for Site Builder click-to-edit. | `<div {{ jw_attributes(block) }}>` |
| `render_block(block)` | Renders theme and app blocks in the `{% default %}` switch case. | `{{ render_block(block) }}` |

---

#### Connecting Sections to Store Data (Data Binding)

##### How Sections Bind to Live Storefront Data

When developing JoonWeb theme sections, components can be static UI elements (such as hero banners configured via `section.settings`), or **dynamic data-bound sections** that display live e-commerce catalog items, blog feeds, or shopping cart drawers.

JoonWeb enables this through **Schema Data Binding**. By adding the `"type"` key to the root of your section's `{% rules %}` JSON schema, the backend engine automatically queries the store database and injects live objects directly into the section template scope:

```json
{% rules %}
{
  "name": "Featured Products Grid",
  "type": "ProductFeed",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Trending Products" },
    { "type": "number", "id": "limit", "label": "Products count", "default": 8 }
  ],
  "presets": [{ "name": "Featured Products Grid", "category": "Products" }]
}
{% endrules %}
```

When rendered on the storefront, the engine detects `"type": "ProductFeed"` and automatically hydrates the `products` array with live catalog data.

##### Complete Section Type & Data Binding Blueprint

Here is the complete reference of section types and the backend objects they activate:

| Schema `"type"` | Injected Template Variables | Primary Section Use Case |
|---|---|---|
| `"ProductFeed"` | `products` | Product grid, trending slider, recommendation carousel |
| `"CollectionFeed"` | `collection.items` | Category cards, featured collections list |
| `"catalogue"` | `catalogue.collections` | Multi-tab category browser with nested product cards |
| `"cart"` | `cart` | Slide-out cart drawer, cart page template |
| `"BlogFeed"` | `blog.items`, `blog.category` | Recent blog news grid, editorial articles carousel |
| `"blog"` / `"blog-post"` | `blog` | Editorial single-article detail page with tags and related posts |
| `"pricing"` / `"plans"` | `plans` | Membership subscription tiers, pricing comparison table |
| `"siteform"` | `block.form` | Dynamic lead generation form with CSRF and CRM integration |
| *(None / Custom)* | `site`, `theme`, `section`, `user`, `query` | Hero banner, features grid, FAQ accordion, testimonials |

##### 1. Building a Dynamic Product Grid (type: "ProductFeed")

To display live store products with images, prices, compare-at discounts, and one-click add to cart, declare `"type": "ProductFeed"`:

```jw
{# 1. SECTION WRAPPER #}
<section id="jw-section-{{ section.id }}" class="py-5 {{ section.colors | default('background5') }}">
  <div class="jw-container" data-id="{{ section.id }}">
    
    {% if section.settings.heading %}
      <div class="text-center mb-5">
        <h2 class="fontStyle2">{{ section.settings.heading }}</h2>
        {% if section.settings.subheading %}
          <p class="fontStyle7 text-muted">{{ section.settings.subheading }}</p>
        {% endif %}
      </div>
    {% endif %}

    {# 2. PRODUCTS LOOP #}
    <div class="row g-4">
      {% for product in products %}
        <div class="col-lg-3 col-md-4 col-sm-6">
          <div class="product-card card h-100 p-3 border rounded shadow-sm">
            {% if product.ribbon %}
              <span class="badge bg-danger position-absolute top-0 start-0 m-3">{{ product.ribbon }}</span>
            {% endif %}

            <a href="{{ product.url }}" class="d-block mb-3 text-center">
              <img src="{{ product.cover }}" alt="{{ product.cover_alt | default(product.title) }}" class="img-fluid rounded" style="max-height: 220px; object-fit: contain;">
            </a>

            <h5 class="fontStyle5 flex-grow-1">
              <a href="{{ product.url }}" class="text-decoration-none text-dark">{{ product.title }}</a>
            </h5>

            <div class="pricing d-flex gap-2 align-items-center my-3">
              <span class="sale-price fontStyle7 fw-bold text-primary">{{ site.currency }}{{ product.sale_price }}</span>
              {% if product.price and product.price_raw > product.sale_price_raw %}
                <span class="compare-price fontStyle8 text-muted text-decoration-line-through">{{ site.currency }}{{ product.price }}</span>
              {% endif %}
            </div>

            {# 1-Click Add to Cart via JWCart #}
            {% if product.in_stock %}
              <button class="btns btns-sm background1 w-100 text-center" 
                      onclick="JWCart.add('redirect', '{{ product.default_varient }}', 1)">
                Add to Cart
              </button>
            {% else %}
              <button class="btns btns-sm btn-secondary w-100 text-center" disabled>Out of Stock</button>
            {% endif %}
          </div>
        </div>
      {% endfor %}
    </div>

  </div>
</section>

{# 3. RULES SCHEMA #}
{% rules %}
{
  "name": "Featured Products Grid",
  "type": "ProductFeed",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Trending Products" },
    { "type": "text", "id": "subheading", "label": "Subheading", "default": "Discover our handpicked selections" },
    { "type": "number", "id": "limit", "label": "Products to show", "default": 8 }
  ],
  "presets": [{ "name": "Featured Products Grid", "category": "Products" }]
}
{% endrules %}
```

##### 2. Building an Interactive Cart Drawer (type: "cart")

To create a slide-out cart drawer or mini-cart, set `"type": "cart"` in your rules. This injects the `cart` object with all active line items and summary totals:

```jw
{# Cart Drawer Section Template #}
<div id="cart-drawer-{{ section.id }}" class="cart-drawer offcanvas offcanvas-end" tabindex="-1">
  <div class="offcanvas-header border-bottom">
    <h5 class="offcanvas-title fontStyle4">Your Shopping Cart</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas"></button>
  </div>

  <div class="offcanvas-body d-flex flex-column">
    {% if cart.items %}
      <div class="cart-items flex-grow-1 overflow-auto">
        {% for item in cart.items %}
          <div class="cart-item d-flex align-items-center mb-3 pb-3 border-bottom">
            <img src="{{ item.cover }}" width="65" height="65" class="rounded object-fit-cover" alt="{{ item['cover.alt'] }}">
            
            <div class="item-info ms-3 flex-grow-1">
              <a href="{{ item.product_url }}" class="fontStyle6 fw-bold text-decoration-none text-dark">{{ item.title }}</a>
              <div class="fontStyle8 text-muted">{{ item.varients }}</div>
              <div class="fontStyle7 fw-bold mt-1 text-primary">{{ site.currency }}{{ item.sale_price * item.qty }}</div>
            </div>

            {# Quantity Mutation Controls via JWCart.update #}
            <div class="quantity-control d-flex align-items-center border rounded">
              <button class="btn btn-sm px-2 py-0" onclick="JWCart.update('redirect', '{{ item.hash }}', -1, 'negative', '{{ item.product_id }}')">-</button>
              <span class="px-2 fontStyle8">{{ item.qty }}</span>
              <button class="btn btn-sm px-2 py-0" onclick="JWCart.update('redirect', '{{ item.hash }}', 1, 'positive', '{{ item.product_id }}')">+</button>
            </div>
          </div>
        {% endfor %}
      </div>

      {# Cart Summary & Checkout #}
      <div class="cart-footer border-top pt-3 mt-3">
        <div class="d-flex justify-content-between mb-2">
          <span class="fontStyle7">Subtotal:</span>
          <strong>{{ site.currency }}{{ cart.subtotal }}</strong>
        </div>
        {% if cart.discount and cart.discount != '0.00' %}
          <div class="d-flex justify-content-between mb-2 text-success">
            <span class="fontStyle8">Savings:</span>
            <strong>-{{ site.currency }}{{ cart.discount }}</strong>
          </div>
        {% endif %}
        <div class="d-flex justify-content-between fontStyle4 mb-3 pt-2 border-top">
          <span>Total:</span>
          <strong>{{ site.currency }}{{ cart.total }}</strong>
        </div>

        {# 1-Click Hosted Checkout Trigger #}
        <a href="javascript:void(0);" id="jwCheckout__nav" class="btns btns-lg background1 w-100 text-center" {{ cart.checkout }}>
          Checkout Now
        </a>
      </div>
    {% else %}
      <div class="empty-state text-center py-5 my-auto">
        <i class="fa fa-shopping-bag fa-3x text-muted mb-3"></i>
        <p class="fontStyle6">Your shopping cart is currently empty.</p>
        <a href="{{ root.url }}/collections" class="btns btns-md background1 mt-2">Start Shopping</a>
      </div>
    {% endif %}
  </div>
</div>

{% rules %}
{
  "name": "Cart Drawer",
  "type": "cart",
  "settings": [],
  "presets": [{ "name": "Cart Drawer", "category": "Cart" }]
}
{% endrules %}
```

##### 3. Building a Blog News Feed (type: "BlogFeed")

To display recent news, journal articles, or editorial guides, set `"type": "BlogFeed"`:

```jw
<section class="py-5 background5">
  <div class="jw-container">
    <h2 class="fontStyle2 text-center mb-5">{{ section.settings.title | default("From the Journal") }}</h2>

    <div class="row g-4">
      {% for post in blog.items %}
        <div class="col-md-4">
          <div class="card h-100 border-0 shadow-sm rounded overflow-hidden">
            {% if post.img %}
              <a href="{{ post.url }}">
                <img src="{{ post.img }}" class="card-img-top" style="height: 220px; object-fit: cover;" alt="{{ post['img.alt'] }}">
              </a>
            {% endif %}
            
            <div class="card-body p-4 d-flex flex-column">
              <div class="meta text-muted fontStyle8 mb-2">
                <span>{{ post.created }}</span> &bull; <span>{{ post.categoryName }}</span>
              </div>
              <h5 class="fontStyle5 mb-2"><a href="{{ post.url }}" class="text-decoration-none text-dark">{{ post.title }}</a></h5>
              <p class="fontStyle7 text-muted flex-grow-1">{{ post.description }}</p>
              <a href="{{ post.url }}" class="fontStyle8 fw-bold text-primary text-decoration-none mt-2">Read More &rarr;</a>
            </div>
          </div>
        </div>
      {% endfor %}
    </div>
  </div>
</section>

{% rules %}
{
  "name": "Blog News Feed",
  "type": "BlogFeed",
  "settings": [
    { "type": "text", "id": "title", "label": "Heading", "default": "Latest Stories" }
  ],
  "presets": [{ "name": "Blog News Feed", "category": "Blog" }]
}
{% endrules %}
```

##### Global Store Context (Available in EVERY Section)

Even when a section has **no special type** (or custom UI controls), the JoonWeb engine always provides global store variables:

| Variable | Description | Common Expressions |
|---|---|---|
| `site` | Store merchant identity & settings | `{{ site.title }}`, `{{ site.currency }}`, `{{ site.phone }}`, `{{ site.email }}` |
| `theme` | Design system configuration tokens | `{{ theme.colors.color1.value }}`, `{{ theme.fontStyle.heading }}` |
| `section` | Active section instance metadata | `{{ section.id }}`, `{{ section.settings.heading }}`, `{{ section.blocks }}` |
| `user` | Authenticated customer account | `{% if user %}{{ user.username }} ({{ user.orders_count }} orders){% endif %}` |
| `query` | URL query parameters | `{{ query.page }}`, `{{ query.sort_by }}` |
| `current_url` | Full active page URL | `{{ current_url }}` |
| `root` | Root paths for storefront linking | `<a href="{{ root.url }}/collections">Collections</a>` |

> [!TIP]
> **Complete Property Reference**: For an exhaustive, property-by-property breakdown of every object and model, visit the **[JW Language Storefront Objects Reference](https://joonweb.dev/jw-language/syntax-and-logic/backend-objects)**.

---


### Production Examples

#### Production-Ready Section Templates

##### Overview

Below are 6 production-ready section examples for JoonWeb themes. Each example includes the full `.jw` template and its corresponding `{% rules %}` JSON schema.

##### 1. Hero Banner Section

A customizable hero section with title, subtitle, CTA button, and hero image block:

```jw
{% set bg_color = section.settings.bg_color | default("#0f172a") %}
{% set padding = section.settings.padding | default(80) %}

<section id="jw-section-{{ section.id }}" style="background: {{ bg_color }}; padding: {{ padding }}px 0;">
    <div class="jw-container" data-id="{{ section.id }}">
        {% for block in section.blocks %}
            {% switch block.type %}
                {% case "hero_text" %}
                    <div class="hero-text-content" {{ jw_attributes(block) }}>
                        <h1 class="fontStyle1">{{ block.settings.title | default("Transform Your Store") }}</h1>
                        <p class="fontStyle7">{{ block.settings.subtitle }}</p>
                        {% if block.settings.button.url %}
                            <a href="{{ block.settings.button.url }}" class="btn-primary" target="{{ block.settings.button.target }}">
                                {{ block.settings.button.label | default("Explore Now") }}
                            </a>
                        {% endif %}
                    </div>
                {% case "hero_image" %}
                    <div class="hero-image-wrapper" {{ jw_attributes(block) }}>
                        <img src="{{ block.settings.image | asset_url }}" alt="Hero Banner">
                    </div>
                {% default %}
                    {{ render_block(block) }}
            {% endswitch %}
        {% endfor %}
    </div>
</section>

{% rules %}
{
  "name": "Hero Banner",
  "settings": [
    { "type": "color_background", "id": "bg_color", "label": "Background Color", "default": "#0f172a" },
    { "type": "range", "id": "padding", "label": "Vertical Padding", "min": 20, "max": 150, "step": 10, "unit": "px", "default": 80 }
  ],
  "blocks": [
    {
      "type": "hero_text",
      "name": "Hero Text & Button",
      "settings": [
        { "type": "quickEditor", "id": "title", "label": "Title", "default": "Transform Your Store" },
        { "type": "textarea", "id": "subtitle", "label": "Subtitle", "default": "Build stunning storefronts with JoonWeb." },
        { "type": "url", "id": "button", "label": "CTA Button", "default": { "url": "/collections", "label": "Shop Now", "target": "_self" } }
      ]
    },
    {
      "type": "hero_image",
      "name": "Hero Image",
      "settings": [
        { "type": "image_picker", "id": "image", "label": "Banner Image" }
      ]
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [{ "name": "Hero Banner", "settings": {} }]
}
{% endrules %}
```

##### 2. Product Feed Section

Renders dynamic products using the `products` array and `JWCart.add` shopping cart engine:

```jw
<section id="jw-section-{{ section.id }}" class="product-feed-section">
    <div class="jw-container" data-id="{{ section.id }}">
        <h2 class="fontStyle2 text-center mb-8">{{ section.settings.title | default("Featured Products") }}</h2>
        <div class="row">
            {% for product in products %}
                <div class="col-lg-3 col-md-4 col-6 mb-6">
                    <div class="product-card background1 p-4 rounded-xl shadow-sm">
                        <img src="{{ product.cover }}" alt="{{ product.title }}" class="rounded-lg mb-3 w-full h-48 object-cover">
                        <h5 class="fontStyle3 mb-2"><a href="{{ product.url }}">{{ product.title }}</a></h5>
                        <div class="fontStyle7 font-bold text-primary mb-3">{{ site.currency }} {{ product.sale_price }}</div>
                        <button class="btn-sm btn-outline w-full" onclick="JWCart.add('redirect','{{ product.default_varient }}',1)">
                            Add to Cart
                        </button>
                    </div>
                </div>
            {% endfor %}
        </div>
    </div>
</section>

{% rules type: "ProductFeed" %}
{
  "name": "Product Feed",
  "settings": [
    { "type": "text", "id": "title", "label": "Section Title", "default": "Featured Products" },
    { "type": "number", "id": "limit", "label": "Number of Products", "default": 8 }
  ],
  "blocks": [
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [{ "name": "Product Feed", "settings": {} }]
}
{% endrules %}
```

##### 3. Header Navigation Section

Uses `section.navigation` array to render responsive navigation links and logo:

```jw
<header id="jw-section-{{ section.id }}" class="site-header {% if section.settings.enable_sticky %}sticky-header{% endif %}">
    <div class="jw-container flex items-center justify-between py-4">
        <!-- Logo -->
        <a href="/" class="logo-link">
            {% if section.settings.logo %}
                <img src="{{ section.settings.logo | asset_url }}" style="height: {{ section.settings.logo_height }}px;" alt="Logo">
            {% else %}
                <span class="fontStyle2">{{ site.name | default("Store") }}</span>
            {% endif %}
        </a>
        
        <!-- Navigation Links -->
        <nav class="nav-menu flex gap-6">
            {% for menu in section.navigation %}
                <a href="{{ menu.link }}" class="fontStyle7 hover:text-primary">{{ menu.label }}</a>
            {% endfor %}
        </nav>
        
        <!-- Cart Action -->
        <div class="header-actions flex items-center gap-4">
            <a href="/cart" class="cart-icon-btn flex items-center gap-1 fontStyle7">
                <i class="fas fa-shopping-cart"></i>
                <span>Cart</span>
            </a>
        </div>
    </div>
</header>

{% rules %}
{
  "name": "Header Navigation",
  "settings": [
    { "type": "image_picker", "id": "logo", "label": "Logo Image" },
    { "type": "range", "id": "logo_height", "label": "Logo Height (px)", "min": 20, "max": 120, "step": 5, "default": 40 },
    { "type": "checkbox", "id": "enable_sticky", "label": "Enable Sticky Header", "default": true }
  ],
  "blocks": [
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [{ "name": "Header Navigation", "settings": {} }]
}
{% endrules %}
```

##### 4. Blog Details & Sidebar Section

Uses the global `blog` object with settings for post title, content body, and sidebar widgets:

```jw
<article id="jw-section-{{ section.id }}" class="blog-article-section py-12">
    <div class="jw-container grid grid-cols-1 lg:grid-cols-12 gap-8">
        <div class="lg:col-span-8">
            {% for block in section.blocks %}
                {% switch block.type %}
                    {% case "blog_title" %}
                        <h1 class="fontStyle1 mb-4" {{ jw_attributes(block) }}>{{ blog.title }}</h1>
                    {% case "blog_content" %}
                        <div class="blog-content prose max-w-none" {{ jw_attributes(block) }}>{{ blog.article }}</div>
                    {% default %}
                        {{ render_block(block) }}
                {% endswitch %}
            {% endfor %}
        </div>
        
        <!-- Sidebar -->
        <aside class="lg:col-span-4 space-y-6">
            {% for block in section.blocks %}
                {% if block.type == "blog_sidebar" %}
                    <div class="sidebar-widget background2 p-6 rounded-xl" {{ jw_attributes(block) }}>
                        {% for subblock in block.blocks %}
                            {% if subblock.type == "popular_posts" %}
                                <h4 class="fontStyle4 mb-4">{{ subblock.settings.heading | default("Popular Posts") }}</h4>
                                <ul class="space-y-2">
                                    {% for post in blog.popular_post %}
                                        <li><a href="{{ post.url }}" class="fontStyle8 hover:underline">{{ post.title }}</a></li>
                                    {% endfor %}
                                </ul>
                            {% endif %}
                        {% endfor %}
                    </div>
                {% endif %}
            {% endfor %}
        </aside>
    </div>
</article>

{% rules %}
{
  "name": "Blog Details",
  "settings": [],
  "blocks": [
    { "type": "blog_title", "name": "Blog Title", "settings": [] },
    { "type": "blog_content", "name": "Blog Content", "settings": [] },
    {
      "type": "blog_sidebar",
      "name": "Sidebar Widget",
      "blocks": [
        {
          "type": "popular_posts",
          "name": "Popular Posts List",
          "settings": [
            { "type": "text", "id": "heading", "label": "Widget Heading", "default": "Popular Posts" }
          ]
        }
      ]
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [{ "name": "Blog Details", "settings": {} }]
}
{% endrules %}
```

##### 5. Footer Section

Renders multi-column navigation menus, social links, and copyright text:

```jw
<footer id="jw-section-{{ section.id }}" class="site-footer background1 py-16">
    <div class="jw-container grid grid-cols-1 md:grid-cols-4 gap-8">
        {% for block in section.blocks %}
            {% if block.type == "column" %}
                <div class="footer-col" {{ jw_attributes(block) }}>
                    <h4 class="fontStyle4 mb-4">{{ block.settings.heading }}</h4>
                    {% if block.blocks %}
                        <ul class="space-y-2">
                            {% for subblock in block.blocks %}
                                {% if subblock.type == "navigation" and subblock.settings.links %}
                                    {% for link in subblock.settings.links %}
                                        <li><a href="{{ link.link }}" class="fontStyle8 hover:underline">{{ link.label }}</a></li>
                                    {% endfor %}
                                {% endif %}
                            {% endfor %}
                        </ul>
                    {% endif %}
                </div>
            {% endif %}
        {% endfor %}
    </div>
    <div class="border-t border-slate-700 mt-12 pt-6 text-center fontStyle9">
        {{ site.name }} &copy; {{ "now" | date("Y") }}. All rights reserved.
    </div>
</footer>

{% rules %}
{
  "name": "Footer",
  "settings": [],
  "blocks": [
    {
      "type": "column",
      "name": "Footer Column",
      "settings": [
        { "type": "text", "id": "heading", "label": "Column Heading", "default": "Quick Links" }
      ],
      "blocks": [
        {
          "type": "navigation",
          "name": "Navigation Links",
          "settings": []
        }
      ]
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [{ "name": "Footer", "settings": {} }]
}
{% endrules %}
```

##### 6. Dynamic Contact Form Section

Uses the `siteform` block type to render lead collection forms with CSRF security tokens:

```jw
<section id="jw-section-{{ section.id }}" class="contact-form-section py-12">
    <div class="jw-container max-w-2xl mx-auto">
        <h2 class="fontStyle2 text-center mb-8">{{ section.settings.title | default("Get in Touch") }}</h2>
        {% for block in section.blocks %}
            {% if block.type == "siteform" and block.form %}
                <form class="jw_dynamic_form space-y-4 background2 p-8 rounded-2xl shadow-sm" {{ jw_attributes(block) }}>
                    <input type="hidden" name="csrf_token" value="{{ block.form.csrf }}">
                    {% for field in block.form.fields %}
                        <div class="form-group space-y-1">
                            <label class="fontStyle8 font-semibold">{{ field.label }}</label>
                            {% if field.type == "text" %}
                                <input type="text" name="{{ field.name }}" class="w-full px-4 py-2.5 rounded-lg border border-slate-300 fontStyle7" placeholder="{{ field.placeholder }}"{% if field.required == "yes" %} required{% endif %}>
                            {% elseif field.type == "textarea" %}
                                <textarea name="{{ field.name }}" rows="4" class="w-full px-4 py-2.5 rounded-lg border border-slate-300 fontStyle7" placeholder="{{ field.placeholder }}"></textarea>
                            {% endif %}
                        </div>
                    {% endfor %}
                    <button type="submit" class="btn-primary w-full py-3 fontStyle7 font-bold">
                        {{ block.form.submit_label | default("Send Message") }}
                    </button>
                </form>
            {% endif %}
        {% endfor %}
    </div>
</section>

{% rules %}
{
  "name": "Contact Form",
  "settings": [
    { "type": "text", "id": "title", "label": "Section Title", "default": "Get in Touch" }
  ],
  "blocks": [
    {
      "type": "siteform",
      "name": "Lead Form",
      "settings": []
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [{ "name": "Contact Form", "settings": {} }]
}
{% endrules %}
```

---

#### Header

```html
{% set bg_color = section.settings.bg_color | default("#ffffff") %}
{% set text_color = section.settings.text_color | default("#000000") %}

<header id="jw-section-{{ section.id }}" style="background-color: {{ bg_color }}; color: {{ text_color }}; padding: 15px 20px; box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);">
    <div class="jw-container d-flex justify-content-between align-items-center">
        
        {# LOGO #}
        <div class="logo">
            {% set style_img = section.settings.logo | asset_url %} 
            {% if style_img is empty or style_img == "" %} 
                {% set style_img = "https://images.unsplash.com/photo-1523275335684-37898b6baf30?auto=format&fit=crop&w=150&q=80" %} 
            {% endif %}
            <a href="/">
                <img src="{{ style_img }}" alt="Site Logo" style="max-height: 50px;" onerror="this.onerror=null; this.src='https://images.unsplash.com/photo-1523275335684-37898b6baf30?auto=format&fit=crop&w=150&q=80';">
            </a>
        </div>

        {# NAVIGATION #}
        {% if section.navigation %}
        <nav class="desktop-menu d-none d-lg-block">
            <ul class="d-flex list-unstyled m-0 gap-4 fontStyle7">
                {% for menu in section.navigation %}
                <li class="menu-item position-relative">
                    <a href="{{ menu.link }}" target="{{ menu.target }}" style="color: {{ text_color }}; text-decoration: none;">
                        {{ menu.label }}
                        {% if menu.children %} <i class="fa fa-angle-down ms-1"></i> {% endif %}
                    </a>
                    
                    {# DROPDOWN LEVEL 1 #}
                    {% if menu.children %}
                    <ul class="dropdown-menu list-unstyled position-absolute bg-white shadow-sm p-2" style="display: none; min-width: 150px; top: 100%;">
                        {% for submenu in menu.children %}
                        <li>
                            <a href="{{ submenu.link }}" target="{{ submenu.target }}" class="d-flex align-items-center p-2 text-dark text-decoration-none">
                                {% if submenu.icon %}
                                <img src="{{ submenu.icon }}" alt="{{ submenu.alt | default('icon') }}" class="me-2" style="width: 20px;">
                                {% endif %}
                                {{ submenu.label }}
                            </a>
                        </li>
                        {% endfor %}
                    </ul>
                    {% endif %}
                </li>
                {% endfor %}
            </ul>
        </nav>
        {% endif %}

        {# CTA BUTTON #}
        <div class="header-actions">
            {% for btn in section.settings.cta_button %}
                <a href="{{ btn.href | default('#') }}" class="btn btn-primary" style="background-color: var(--color1); color: var(--color5);">
                    {{ btn.label | default('Get Started') }}
                </a>
            {% endfor %}
        </div>

    </div>
</header>

<style>
/* Simple CSS to handle hover state for dropdowns in this sample */
.menu-item:hover .dropdown-menu {
    display: block !important;
}
</style>

{% rules %}
{
  "name": "Premium Header",
  "blocks": [
    {
      "type": "navigation"
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "settings": [
    {
      "type": "image_picker",
      "id": "logo",
      "label": "Site Logo"
    },
    {
      "type": "color_background",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#ffffff"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text Color",
      "default": "#000000"
    },
    {
      "type": "button",
      "id": "cta_button",
      "label": "Call to Action"
    }
  ],
  "presets": [
    {
      "blocks": [
        {
          "type": "navigation",
          "settings": {
            "links": [
              { "label": "Home", "type": "home" },
              { "label": "About", "type": "none" },
              { "label": "Services", "type": "none" }
            ]
          }
        }
      ]
    }
  ]
}
{% endrules %}
```

---

#### Footer

```html
{% set bg_color = section.settings.bg_color | default("#111827") %}
{% set text_color = section.settings.text_color | default("#f9fafb") %}
{% set pad_y = section.settings.padding_y | default(60) %}

<footer id="jw-section-{{ section.id }}" style="background-color: {{ bg_color }}; color: {{ text_color }}; padding: {{ pad_y }}px 20px;">
    <div class="jw-container" data-id="{{ section.id }}">
        <div class="row">
            
            {# RENDER COLUMNS #}
            {% if section.blocks is defined and section.blocks|length > 0 %}
                {% for block in section.blocks %}
                    
                    {% switch block.type %}
                    {% case "columns" %}
                        <div class="col-lg-3 col-md-6 mb-4" {{ jw_attributes(block) }}>
                            <h4 class="fontStyle4 mb-4" style="color: {{ text_color }};">{{ block.settings.heading | default("Quick Links") }}</h4>
                            
                            {# RENDER NESTED BLOCKS (NAVIGATION OR OTHERS) #}
                            {% if block.blocks %}
                                {% for subblock in block.blocks %}
                                    
                                    {% if subblock.type == "navigation" %}
                                        <ul class="list-unstyled fontStyle7" {{ jw_attributes(subblock) }}>
                                            {% if subblock.settings.links %}
                                                {% for menu in subblock.settings.links %}
                                                    <li class="mb-2">
                                                        <a href="{{ menu.link | default('#') }}" target="{{ menu.target }}" style="color: {{ text_color }}; opacity: 0.8; text-decoration: none;">
                                                            {% if menu.icon != "" %}
                                                                <span class="me-2">{{ menu.icon | raw }}</span> {# Usually SVGs #}
                                                            {% endif %}
                                                            {{ menu.label | default("Menu Item") }}
                                                        </a>
                                                    </li>
                                                {% endfor %}
                                            {% else %}
                                                <li>[ Click to Edit Menu ]</li>
                                            {% endif %}
                                        </ul>
                                    {% else %}
                                        {{ render_block(subblock) }}
                                    {% endif %}
                                    
                                {% endfor %}
                            {% endif %}
                        </div>
                    
                    {% default %}
                        {{ render_block(block) }}
                    {% endswitch %}

                {% endfor %}
            {% endif %}

        </div>

        {# SOCIAL ICONS #}
        <div class="border-top mt-5 pt-4 d-flex justify-content-between align-items-center">
            <p class="mb-0 fontStyle9" style="opacity: 0.7;">&copy; {{ "now"|date("Y") }} Your Company. All rights reserved.</p>
            
            {% if section.settings.social_links %}
            <ul class="list-unstyled d-flex gap-3 mb-0">
                {% for item in section.settings.social_links %}
                <li>
                    <a href="{{ item.href }}" target="{{ item.target }}" style="color: {{ text_color }}; font-size: 20px;">
                        {{ item.icon | raw }}
                    </a>
                </li>
                {% endfor %}
            </ul>
            {% endif %}
        </div>
    </div>
</footer>

{% rules %}
{
  "name": "Premium Footer",
  "blocks": [
    {
      "type": "columns",
      "name": "Footer Column",
      "settings": [
        {
          "type": "text",
          "id": "heading",
          "label": "Column Heading",
          "default": "Resources"
        }
      ],
      "blocks": [
        { "type": "navigation", "name": "Column Menu" },
        { "type": "themes" },
        { "type": "apps" }
      ]
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "settings": [
    {
      "type": "color_background",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#111827"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text Color",
      "default": "#f9fafb"
    },
    {
      "type": "range",
      "id": "padding_y",
      "label": "Vertical Padding",
      "min": 20,
      "max": 150,
      "step": 10,
      "unit": "px",
      "default": 60
    },
    {
      "type": "socialicon",
      "id": "social_links",
      "label": "Social Media Links"
    }
  ],
  "presets": [
    {
      "blocks": [
        {
          "type": "columns",
          "settings": { "heading": "Company" },
          "blocks": [{ "type": "navigation" }]
        },
        {
          "type": "columns",
          "settings": { "heading": "Support" },
          "blocks": [{ "type": "navigation" }]
        }
      ]
    }
  ]
}
{% endrules %}
```

---

#### Blog Grid Feed

```html
{% set bg_color = section.settings.bg_color | default("#ffffff") %}
{% set pad_y = section.settings.padding_y | default(60) %}

<section id="jw-section-{{ section.id }}" style="background-color: {{ bg_color }}; padding: {{ pad_y }}px 20px;">
    <div class="jw-container" data-id="{{ section.id }}">
        
        {# SECTION HEADER #}
        <div class="text-center mb-5">
            <h2 class="fontStyle2" style="color: var(--color1);">{{ section.settings.title | default('Latest Articles') }}</h2>
            <p class="fontStyle7 text-muted">{{ section.settings.subtitle | default('Stay updated with our latest news.') }}</p>
        </div>

        {# BLOG FEED LOOP #}
        {% if blog.items %}
            <div class="row g-4 {% if blog.items|length <= 2 %}justify-content-center{% endif %}">
                {% for itemkey, blog_post in blog.items %}
                    <div class="col-lg-4 col-md-6 col-sm-12">
                        <div class="card h-100 border-0 shadow-sm" style="border-radius: 12px; overflow: hidden; background: #fff;">
                            
                            {# IMAGE #}
                            <a href="{{ blog_post.url }}" class="d-block" style="height: 200px; overflow: hidden;">
                                <img src="{{ blog_post.img }}" alt="{{ blog_post['img.alt'] | default(blog_post.title) }}" 
                                     style="width: 100%; height: 100%; object-fit: cover; transition: transform 0.3s;" 
                                     onerror="this.onerror=null; this.src='https://images.unsplash.com/photo-1499750310107-5fef28a66643?auto=format&fit=crop&w=800&q=80';"
                                     onmouseover="this.style.transform='scale(1.05)';" onmouseout="this.style.transform='scale(1)';">
                            </a>

                            {# CONTENT #}
                            <div class="card-body p-4">
                                {# META DATA #}
                                {% if blog_post.created or blog_post.author or blog_post.views %}
                                    <div class="d-flex gap-3 mb-3 fontStyle9 text-muted" style="font-size: 0.85rem;">
                                        {% if blog_post.created %}<span><i class="fa-regular fa-calendar me-1"></i> {{ blog_post.created|date("M d, Y") }}</span>{% endif %}
                                        {% if blog_post.author %}<span><i class="fa-regular fa-user me-1"></i> {{ blog_post.author }}</span>{% endif %}
                                        {% if blog_post.views %}<span><i class="fa-regular fa-eye me-1"></i> {{ blog_post.views }} Views</span>{% endif %}
                                    </div>
                                {% endif %}

                                {# TITLE & DESC #}
                                {% if blog_post.title %}
                                    <h4 class="card-title fontStyle4 mb-3">
                                        <a href="{{ blog_post.url }}" style="color: var(--color1); text-decoration: none;">{{ blog_post.title }}</a>
                                    </h4>
                                {% endif %}
                                
                                {% if blog_post.description %}
                                    <p class="card-text fontStyle7 text-muted" style="display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden;">
                                        {{ blog_post.description }}
                                    </p>
                                {% endif %}
                                
                                {# READ MORE #}
                                {% if blog_post.url %}
                                    <a href="{{ blog_post.url }}" class="fontStyle7 fw-bold mt-3 d-inline-block" style="color: var(--color1); text-decoration: none;">
                                        Read More <i class="fa fa-arrow-right ms-1"></i>
                                    </a>
                                {% endif %}
                            </div>

                        </div>
                    </div>
                {% endfor %}
            </div>
        {% else %}
            <div class="text-center py-5">
                <p class="text-muted fontStyle7">No blog posts available at the moment.</p>
            </div>
        {% endif %}

    </div>
</section>

{% rules %}
{
  "name": "Blog Grid Feed",
  "type": "BlogFeed",
  "blocks": [
    { "type": "themes" },
    { "type": "apps" }
  ],
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Section Title",
      "default": "Latest Articles"
    },
    {
      "type": "text",
      "id": "subtitle",
      "label": "Section Subtitle",
      "default": "Stay updated with our latest news."
    },
    {
      "type": "color_background",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#ffffff"
    },
    {
      "type": "range",
      "id": "padding_y",
      "label": "Vertical Padding",
      "min": 0,
      "max": 150,
      "step": 10,
      "unit": "px",
      "default": 60
    }
  ],
  "presets": []
}
{% endrules %}
```

---

#### Product Grid Feed

```html
{% set bg_color = section.settings.bg_color | default("#ffffff") %}
{% set text_color = section.settings.text_color | default("#333333") %}
{% set pad_y = section.settings.padding_y | default(60) %}

<section id="jw-section-{{ section.id }}" style="background-color: {{ bg_color }}; padding: {{ pad_y }}px 20px;">
    <div class="jw-container" data-id="{{ section.id }}">
        
        <div class="text-center mb-5">
            <h2 class="fontStyle2" style="color: {{ text_color }};">{{ section.settings.title | default('Featured Products') }}</h2>
        </div>

        {# PRODUCT LOOP #}
        {% if products %}
            <div class="row g-4 {% if products | length < 3 %}justify-content-center{% endif %}">
                {% for product in products %}
                    <div class="col-lg-3 col-md-4 col-sm-6">
                        <div class="card h-100 border-0 shadow-sm product-card position-relative" style="border-radius: 12px; overflow: hidden;">
                            
                            {# RIBBON / TAG #}
                            {% if product.ribbon %}
                                <div class="position-absolute top-0 start-0 m-3 z-index-1">
                                    <span class="badge bg-danger fontStyle9 py-1 px-2">{{ product.ribbon }}</span>
                                </div>
                            {% endif %}
                            
                            {# DISCOUNT TAG #}
                            {% if product.discount %}
                                <div class="position-absolute top-0 start-0 m-3 mt-5 z-index-1">
                                    <span class="badge bg-success fontStyle9 py-1 px-2">{{ product.discount }}</span>
                                </div>
                            {% endif %}

                            {# WISHLIST TOGGLE (CORE CRM LINKED) #}
                            <div class="position-absolute top-0 end-0 m-3 z-index-1">
                                <div class="jw-wishlist-toggle wishlist-icon bg-white rounded-circle d-flex align-items-center justify-content-center shadow-sm" 
                                     style="width: 35px; height: 35px; cursor: pointer; color: #ff4757;"
                                     onclick="customWishlist('custom','{{product.default_varient}}',this);">
                                    <i class="fa-regular fa-heart"></i>
                                </div>
                            </div>

                            {# PRODUCT MEDIA #}
                            <a href="{{ product.url }}" class="d-block position-relative" style="height: 250px; background-color: #f8f9fa;">
                                <img src="{{ product.cover }}" alt="{{ product['cover.alt'] | default(product.title) }}" 
                                     class="primary-img w-100 h-100 object-fit-cover" 
                                     onerror="this.onerror=null; this.src='https://images.unsplash.com/photo-1505740420928-5e560c06d30e?auto=format&fit=crop&w=800&q=80';">
                                
                                {% if product.media %}
                                    <img src="{{ product.media }}" alt="{{ product['media.alt'] | default('hover image') }}" 
                                         class="hover-img position-absolute top-0 left-0 w-100 h-100 object-fit-cover opacity-0 transition-base"
                                         onerror="this.onerror=null; this.style.display='none';">
                                {% endif %}
                            </a>

                            {# PRODUCT INFO #}
                            <div class="card-body text-center p-3">
                                <h5 class="card-title fontStyle6 mb-2">
                                    <a href="{{ product.url }}" style="color: {{ text_color }}; text-decoration: none;">{{ product.title }}</a>
                                </h5>
                                
                                <div class="price-wrapper d-flex justify-content-center gap-2 fontStyle7 mb-3">
                                    {% if product.sale_price %}
                                        <span class="fw-bold text-dark">{{ site.currency }}{{ product.sale_price }}</span>
                                    {% endif %}
                                    {% if product.price %}
                                        <span class="text-muted text-decoration-line-through">{{ site.currency }}{{ product.price }}</span>
                                    {% endif %}
                                </div>

                                {# ADD TO CART (CORE CRM LINKED) #}
                                {% if product.in_stock %}
                                    <button class="btn btn-outline-dark w-100 fontStyle8" onclick="JWCart.add('redirect', '{{product.default_varient}}', 1)">
                                        Add to Cart
                                    </button>
                                {% else %}
                                    <button class="btn btn-secondary w-100 fontStyle8" disabled>
                                        Out of Stock
                                    </button>
                                {% endif %}
                            </div>

                        </div>
                    </div>
                {% endfor %}
            </div>
        {% else %}
            <div class="text-center py-5">
                <p class="text-muted fontStyle7">No products available.</p>
            </div>
        {% endif %}

    </div>
</section>

<style>
/* Product Card Hover Effects */
.product-card .hover-img {
    transition: opacity 0.3s ease;
}
.product-card:hover .hover-img {
    opacity: 1 !important;
}
.product-card:hover .primary-img {
    opacity: 0;
}
.transition-base {
    transition: all 0.3s ease;
}
</style>

{% rules %}
{
  "name": "E-Commerce Product Feed",
  "type": "ProductFeed",
  "blocks": [
    { "type": "themes" },
    { "type": "apps" }
  ],
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Section Title",
      "default": "Featured Products"
    },
    {
      "type": "color_background",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#ffffff"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text Color",
      "default": "#333333"
    },
    {
      "type": "range",
      "id": "padding_y",
      "label": "Vertical Padding",
      "min": 0,
      "max": 150,
      "step": 10,
      "unit": "px",
      "default": 60
    }
  ],
  "presets": []
}
{% endrules %}
```

---

#### Dynamic Site Form

```html
{% set bg_color = section.settings.bg_color | default("#f3f4f6") %}
{% set pad_y = section.settings.padding_y | default(60) %}

<section id="jw-section-{{ section.id }}" style="background-color: {{ bg_color }}; padding: {{ pad_y }}px 20px;">
    <div class="jw-container" data-id="{{ section.id }}">
        
        <div class="row justify-content-center">
            <div class="col-lg-6 col-md-8">
                <div class="card border-0 shadow-lg p-5" style="border-radius: 16px;">
                    
                    <h3 class="fontStyle3 mb-4 text-center">{{ section.settings.title | default("Contact Us") }}</h3>
                    <p class="fontStyle8 text-center text-muted mb-4">{{ section.settings.subtitle | default("We'd love to hear from you.") }}</p>

                    {# DYNAMIC FORM RENDERING #}
                    {% if section.blocks is defined and section.blocks|length > 0 %}
                        {% for block in section.blocks %}
                            
                            {% switch block.type %}
                            {% case "siteform" %}
                                <div {{ jw_attributes(block) }}>
                                    {% if block.form %}
                                    {% set form = block.form %}
                                    
                                    <form class="jw_dynamic_form" name="form_v_{{ form.id }}">
                                        {# SYSTEM REQUIRED HIDDEN FIELDS #}
                                        <input type="hidden" name="csrf_token" value="{{ form.csrf }}">
                                        <signature style="display:none">{{ form.signature }}</signature>

                                        <div class="row g-3">
                                            {% for field in form.fields %}
                                                
                                                <div class="col-12 dynamicField mb-3" 
                                                     data-required="{{ field.required == 'yes' and field.state != 'hide' ? 'yes' : 'no' }}" 
                                                     data-input="{{ field.type }}" 
                                                     data-mode="{{ field.mode }}" 
                                                     {% if field.state == 'hide' %}style="display:none"{% endif %}>
                                                    
                                                    {% if field.hideLabel != "yes" %}
                                                        <label class="form-label fontStyle8 fw-bold">{{ field.label }} {% if field.required == 'yes' %}<span class="text-danger">*</span>{% endif %}</label>
                                                    {% endif %}

                                                    {# RENDER INPUT TYPES #}
                                                    {% if field.type in ["text","email","tel","number","password","date","datetime"] %}
                                                        <input type="{{ field.type == 'datetime' ? 'datetime-local' : field.type }}"
                                                            data-name="{{ field.name }}" data-input="{{ field.type }}" date-mode="{{ field.mode }}"
                                                            class="form-control jw_dynamic_input p-3" 
                                                            placeholder="{{ field.placeholder }}" 
                                                            tooltip="{{ field.tooltip }}" 
                                                            {% if field.required == 'yes' %}required{% endif %} 
                                                            {% if field.maxlength %}maxlength="{{ field.maxlength }}"{% endif %} 
                                                            {% if field.minlength %}minlength="{{ field.minlength }}"{% endif %} 
                                                            errmsg="{{ field.errmsg }}">

                                                    {% elseif field.type == "textarea" %}
                                                        <textarea data-name="{{ field.name }}" class="form-control jw_dynamic_input p-3" data-input="textarea" rows="4" placeholder="{{ field.placeholder }}"></textarea>

                                                    {% elseif field.type == "dropdown" %}
                                                        <select class="form-select jw_dynamic_input p-3" data-input="dropdown">
                                                            {% for opt in field.extra.options %}
                                                                <option value="{{ opt }}">{{ opt }}</option>
                                                            {% endfor %}
                                                        </select>

                                                    {% elseif field.type == "radio" %}
                                                        <div class="d-flex gap-3 mt-2">
                                                            {% for opt in field.extra.options %}
                                                                <div class="form-check jw-radio-group">
                                                                    <input type="radio" class="form-check-input jw_dynamic_input" value="{{ opt }}" name="radio_{{ field.name }}">
                                                                    <label class="form-check-label">{{ opt }}</label>
                                                                </div>
                                                            {% endfor %}
                                                        </div>

                                                    {% elseif field.type == "checkbox" %}
                                                        <div class="form-check mt-2">
                                                            <input type="checkbox" class="form-check-input jw_dynamic_input" name="{{ field.name }}">
                                                            <label class="form-check-label">{{ field.label }}</label>
                                                        </div>
                                                    {% endif %}

                                                </div>

                                            {% endfor %}

                                            {# PAYMENT GATEWAY INJECTION (REQUIRED) #}
                                            {% if form.payment.enabled %}
                                            <div class="col-12 dynamicField paymentItems mb-3" data-input="radio" data-mode="normal">
                                                <label class="form-label fontStyle8 fw-bold">{{ form.payment.label }}</label>
                                                {% for item in form.payment.items %}
                                                    {% set rid = "payrad" ~ form.id ~ loop.index %}
                                                    <div class="form-check jw-radio-group">
                                                        <input type="radio" data-input="radio" date-mode="normal" class="form-check-input jw_dynamic_input" data-name="payItems" name="payItems" id="{{ rid }}" value="uni-{{ loop.index0 }}" required>
                                                        <label class="form-check-label" for="{{ rid }}">{{ item.itemName }}</label>
                                                    </div>
                                                {% endfor %}
                                                <input type="hidden" class="jw_dynamic_input submission_fpv" data-name="submission_fpv" name="submission_fpv" value="" />
                                            </div>
                                            {% endif %}

                                            {# OTP FIELD INJECTION (REQUIRED) #}
                                            {% if form.otp.enabled %}
                                            <div class="col-12 dynamicField otpcode mb-3" style="display:none">
                                                <label class="form-label fontStyle8 fw-bold">Enter OTP</label>
                                                <input type="text" class="form-control jw_dynamic_input p-3">
                                                <a href="#" class="_back2form text-decoration-none mt-2 d-inline-block fontStyle9">Change {{ form.otp.device }}</a>
                                            </div>
                                            {% endif %}

                                            {# CAPTCHA INJECTION (REQUIRED) #}
                                            {% if form.captcha_html %}
                                            <div class="col-12 see-full mb-3">
                                                {{ form.captcha_html | raw }}
                                            </div>
                                            {% endif %}

                                            {# SUBMIT BUTTON #}
                                            <div class="col-12 mt-4">
                                                <input type="hidden" class="_tx_" value="{{ form.id }}">
                                                <button type="submit" class="btn btn-primary w-100 p-3 fontStyle7 fw-bold see-button" style="background-color: var(--color1);">
                                                    {{ form.submit_label | default('Get Started') }}
                                                </button>
                                            </div>

                                        </div>
                                    </form>
                                    
                                    {% endif %}
                                </div>
                            
                            {% default %}
                                {{ render_block(block) }}
                            {% endswitch %}

                        {% endfor %}
                    {% endif %}

                </div>
            </div>
        </div>

    </div>
</section>

{% rules %}
{
  "name": "Dynamic Form Capture",
  "blocks": [
    {
      "type": "siteform",
      "name": "Form Container",
      "settings": []
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Heading",
      "default": "Contact Us"
    },
    {
      "type": "text",
      "id": "subtitle",
      "label": "Sub Heading",
      "default": "We'd love to hear from you."
    },
    {
      "type": "color_background",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#f3f4f6"
    },
    {
      "type": "range",
      "id": "padding_y",
      "label": "Vertical Padding",
      "min": 0,
      "max": 150,
      "step": 10,
      "unit": "px",
      "default": 60
    }
  ],
  "presets": [
    {
      "blocks": [
        {
          "type": "siteform",
          "formType": "basic",
          "fields": [
            {
              "label": "Full Name",
              "placeholder": "John Doe",
              "required": "yes",
              "mode": "system",
              "name": "firstName",
              "type": "text"
            },
            {
              "label": "Email",
              "type": "email",
              "required": "yes",
              "placeholder": "hello@example.com",
              "mode": "system",
              "name": "email"
            },
            {
              "label": "Message",
              "type": "textarea",
              "required": "yes",
              "placeholder": "How can we help?",
              "mode": "system",
              "name": "message"
            }
          ]
        }
      ]
    }
  ]
}
{% endrules %}
```

---


### Conversion Guide

#### Converting Static HTML to Dynamic .jw Sections

##### Overview: The 5-Step Section Conversion Workflow

Converting static HTML into a fully dynamic, merchant-editable JoonWeb section requires 5 straightforward steps:

1. **Identify Editable Elements**: Determine which headings, images, links, and collections should be configurable in the Site Builder.
2. **Implement Scoped CSS**: Namespace all styles with `#{{ section.id }}` to prevent CSS bleed and respect the `{ #` spacing rule.
3. **Bind JW Variables & Dynamic Objects**: Replace static copy with `{{ section.settings.* }}`, `{{ site.currency }}`, and `JWCart` methods.
4. **Render Dynamic Blocks**: Wrap repetitive cards or columns in `{% for block in section.blocks %}` with `{{ jw_attributes(block) }}`.
5. **Attach Embedded {% rules %}**: Define the JSON schema blueprint with settings, blocks, and default presets.

##### Step 1: Start with Static HTML & Bootstrap 5.3

Here is a static Bootstrap 5.3 feature section before conversion:

```html
<!-- Static HTML Example -->
<section class="features-section py-5 bg-light" id="features">
  <div class="container">
    <div class="text-center mb-5">
      <h2 class="fw-bold">Why Shop With Us</h2>
      <p class="text-muted">Premium quality guaranteed with every order</p>
    </div>
    <div class="row g-4">
      <div class="col-md-4">
        <div class="card p-4 text-center border-0 shadow-sm">
          <img src="/images/shipping.svg" class="mb-3 mx-auto" width="48">
          <h4>Fast Express Shipping</h4>
          <p class="text-muted">Dispatched within 24 hours.</p>
        </div>
      </div>
    </div>
  </div>
</section>
```

##### Step 2: Add Scoped Styles & Responsive Padding

Add scoped styles using `#{{ section.id }}`. 

⚠️ **Crucial Invariant**: Always ensure there is a whitespace between `{` and `#` (e.g. `{ #{{ section.id }}`) so the JW Engine does not mistake it for a comment tag (`{#`):

```jw
<style>
  /* Border radius for cards */
  {% if section.desktop.borderRadius %}
    #{{ section.id }} .feature-card {
      border-radius: {{ section.desktop.borderRadius }}px;
    }
  {% endif %}

  /* Responsive padding */
  #{{ section.id }} {
    padding-top: {{ section.mobile.deskPaddingTop | default(40) }}px;
    padding-bottom: {{ section.mobile.deskPaddingBottom | default(40) }}px;
  }
  @media screen and (min-width: 750px) {
    #{{ section.id }} {
      padding-top: {{ section.desktop.deskPaddingTop | default(80) }}px;
      padding-bottom: {{ section.desktop.deskPaddingBottom | default(80) }}px;
    }
  }
</style>
```

##### Step 3: Convert Static Markup into Dynamic JW Template

Replace static text with JW template expressions and block iterations:

```jw
<section class="jw_section section-padding {{ section.colors ? section.colors : 'background5' }}" id="{{ section.id }}">
  <div class="{{ section.desktop.sectionWidth ? section.desktop.sectionWidth : 'container' }}">
    
    {# Section Heading #}
    {% if section.settings.heading %}
      <div class="text-center mb-5">
        <h2 class="fontStyle2 mb-2">{{ section.settings.heading }}</h2>
        {% if section.settings.subheading %}
          <p class="fontStyle7 text-muted">{{ section.settings.subheading }}</p>
        {% endif %}
      </div>
    {% endif %}

    {# Dynamic Blocks Grid #}
    {% if section.blocks is defined and section.blocks | length > 0 %}
      <div class="row g-4">
        {% for block in section.blocks %}
          <div class="col-md-4" {{ jw_attributes(block) }}>
            {% switch block.type %}
              {% case "feature_item" %}
                <div class="feature-card card p-4 text-center border-0 shadow-sm {{ section.colors2 ? section.colors2 : 'background5' }}">
                  {% if block.settings.icon %}
                    <img src="{{ block.settings.icon | asset_url }}" alt="{{ block.settings.title }}" class="mb-3 mx-auto" style="width: 48px; height: 48px; object-fit: contain;">
                  {% endif %}
                  <h4 class="fontStyle4 mb-2">{{ block.settings.title }}</h4>
                  <p class="fontStyle8 text-muted mb-0">{{ block.settings.description }}</p>
                </div>
              {% default %}
                {{ render_block(block) }}
            {% endswitch %}
          </div>
        {% endfor %}
      </div>
    {% endif %}

  </div>
</section>
```

##### Step 4: Append Embedded {% rules %} JSON Schema

Place the `{% rules %}` block at the very end of your `.jw` file to register controls with the Site Builder:

```jw
{% rules %}
{
  "name": "Feature Highlights",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Section Heading",
      "default": "Why Shop With Us"
    },
    {
      "type": "textarea",
      "id": "subheading",
      "label": "Subheading",
      "default": "Premium quality guaranteed with every order"
    },
    {
      "type": "range",
      "id": "borderRadius",
      "label": "Card Border Radius",
      "min": 0,
      "max": 30,
      "step": 2,
      "unit": "px",
      "default": 12
    }
  ],
  "blocks": [
    {
      "type": "feature_item",
      "name": "Feature Item",
      "settings": [
        { "type": "image_picker", "id": "icon", "label": "Feature Icon" },
        { "type": "text", "id": "title", "label": "Title", "default": "Fast Shipping" },
        { "type": "textarea", "id": "description", "label": "Description", "default": "Dispatched within 24 hours." }
      ]
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [
    {
      "name": "Feature Highlights",
      "category": "Promotional",
      "blocks": [
        { "type": "feature_item", "settings": { "title": "Fast Shipping", "description": "Dispatched within 24 hours." } },
        { "type": "feature_item", "settings": { "title": "Secure Payments", "description": "100% encrypted checkout." } },
        { "type": "feature_item", "settings": { "title": "Easy Returns", "description": "7-day hassle-free returns." } }
      ]
    }
  ]
}
{% endrules %}
```

##### Step 5: Quality Checklist for JoonWeb Themes

Before publishing or submitting a section:

- [x] **No Forbidden Tags**: Ensure there are zero mentions of external templating engines. Strictly use JW Engine tags.
- [x] **Comment Collision Check**: Verified that all `{ #{{ section.id }}` styles have spaces between `{` and `#`.
- [x] **Dynamic Click-to-Edit**: `{{ jw_attributes(block) }}` is attached to each block container.
- [x] **Fallback Block Support**: `{{ render_block(block) }}` is called in the `{% default %}` switch branch.
- [x] **Universal App Extension Compatibility**: `{"type": "themes"}` and `{"type": "apps"}` are included in `blocks` array.
- [x] **Valid JSON Schema**: No trailing commas or invalid JSON syntax in `{% rules %}`.

---


### AI Section Skills

#### Build JoonWeb (.JW) Section with ChatGPT

##### Overview & 1-Click Launch with ChatGPT

JoonWeb enables developers, merchants, and theme creators to rapidly generate production-ready `.jw` sections using OpenAI's **ChatGPT** (GPT-4o, ChatGPT Plus, and Custom GPTs).

By pairing ChatGPT with the official **`jw-theme-sections`** skill, you can generate responsive storefront sections with Bootstrap 5.3 utilities, scoped styles, and fully populated JSON rules schemas in seconds.

---

### 🚀 1-Click Execution

Click below to immediately open ChatGPT with the official JoonWeb skill and prompt pre-loaded:

[**⚡ Launch Directly in ChatGPT**](https://chatgpt.com/?hints=search&q=You%20are%20an%20Expert%20JoonWeb%20Theme%20Developer.%20Follow%20the%20official%20JoonWeb%20section%20specifications%20at%20https%3A%2F%2Fjoonweb.dev%2Fskills%2Fjw-theme-sections%2FSKILL.md%20to%20build%20a%20production-ready%20.jw%20section.)

> **Skill File Reference:** [https://joonweb.dev/skills/jw-theme-sections/SKILL.md](https://joonweb.dev/skills/jw-theme-sections/SKILL.md)

##### ChatGPT Prompt Template & Workflow

### JW Language Conditionals & Truthiness
| Legacy Syntax | JW Language Equivalent (Native) |
|---|---|
| `{% if title != blank %}` | `{% if title is not empty %}` or `{% if title != '' %}` |
| `{% if title != nil %}` | `{% if title is not null %}` |
| `{% if title != "" %}` | `{% if title != '' %}` |
| `{% if title != blank and title != nil %}` | `{% if title is defined and title is not empty %}` |
| `{% if title == blank %}` | `{% if title is empty %}` or `{% if title == '' %}` |
| `{% if title == nil %}` | `{% if title is null %}` |

### Master Prompt for ChatGPT

Copy and paste the following prompt into ChatGPT to generate any custom section:

```markdown
You are an Expert JoonWeb Theme Developer. Follow the official specifications:
https://joonweb.dev/skills/jw-theme-sections/SKILL.md

Create a production-ready, ultra-premium [SECTION_NAME] section in .jw format for an [Online Store / Informative Website].

Strict Requirements:
1. Top Comment: {# Copy and paste this code directly into the JoonWeb Theme Editor (.jw file) #}
2. File Order (Mandatory): Variables {% set %} -> <style> (Scoped CSS MUST come BEFORE <section>) -> <section> (Outer HTML container) -> <script> -> {# Do not change if you don't know #} -> {% rules %}.
3. Outer Wrapper: <section id="jw-section-{{ section.id }}" class="xx background{{ sc }} ..." data-xx="1" data-bl="{{ site ? 0 : 1 }}" style="...">.
4. Conditionals: Use != '' (never != blank).
5. Styling: Bootstrap 5.3 + Bootstrap Icons + FontAwesome 6. Scoped CSS using {{ S }} with builder overrides {{ S }}[data-bl="1"].
6. Editable Blocks: <div class="xx-blk" data-jw-block> and {% switch block.type %} ... {% default %} {{ render_block(block) }} {% endswitch %}.
7. Valid Setting Types: ONLY radio (yes/no), quickEditor (<p>...</p>), text, url, image_picker, range, select, color, color_background, header, paragraph, buttons, socialicon. Never use checkbox or textarea.
8. Schema Blocks & Presets: Append {"type": "themes"} and {"type": "apps"} to schema blocks. NEVER include themes or apps in presets blocks.
9. Clean Comments: No unnecessary, bulky decorative comments.
```

### Custom GPT Setup (Optional)
If you are configuring a custom GPT for your development agency or team:
1. In the GPT **Instructions** field, paste the system prompt above.
2. Add `https://joonweb.dev/skills/jw-theme-sections/SKILL.md` to GPT Knowledge.
3. Your GPT is now primed to generate valid single-file `.jw` templates on demand.

##### Ready-to-Use Prompt Examples for ChatGPT

Here are tested prompt examples you can copy and send to ChatGPT right now:

#### 1. Full-Width Hero Banner
```text
Create a full-width Hero Banner section (.jw) for an informative agency website with:
- Background image picker with dark overlay opacity range slider (0% to 100%)
- Large responsive heading and lead paragraph
- Primary CTA button and secondary outline button with link pickers
- Text alignment selector (left, center, right)
- Scoped CSS under #jw-section-{{ section.id }}
- Valid JSON {% rules %} ... {% endrules %} with fully populated default presets
```

#### 2. E-Commerce Featured Product Grid with Instant Cart
```text
Generate an e-commerce Featured Product Grid section in .jw format with:
- Collection selector setting and product count slider (4 to 12)
- Responsive Bootstrap 5.3 grid with column controls (2, 3, or 4 columns)
- Product card featuring: hover zoom effect, discount percentage badge, sale price, MRP strikethrough, and stock badge
- Instant Ajax Add to Cart button using JWCart.add(variantId, 1, this)
- Scoped CSS under #jw-section-{{ section.id }}
- Valid JSON {% rules %} ... {% endrules %} with fully populated default presets
```

#### 3. Customer Testimonials Carousel
```text
Generate an interactive Customer Testimonials section in .jw format with:
- Section header with title and subtitle
- Repeatable blocks for individual testimonials
- Each block containing: 5-star rating display, customer quote text, avatar image picker, customer name, and role/company
- Responsive Bootstrap 5.3 card layout
- Scoped CSS for card hover lift and quotation styling
- Valid JSON {% rules %} ... {% endrules %} with fully populated default presets (3 demo testimonials)
```

##### Production .jw File Anatomy & Output

When generated correctly, your `.jw` section will follow this precise single-file structure:

```html
{# ======================================================== #}
{# JoonWeb Hero Banner Section (.jw)                        #}
{# ======================================================== #}
<section id="jw-section-{{ section.id }}" class="jw-hero-banner position-relative overflow-hidden" style="padding-top: {{ section.settings.padding_top }}px; padding-bottom: {{ section.settings.padding_bottom }}px;">
  <div class="container position-relative z-1 py-5">
    <div class="row align-items-center {% if section.settings.alignment == 'center' %}justify-content-center text-center{% else %}justify-content-start text-start{% endif %}">
      <div class="col-12 col-lg-8">
        {% if section.settings.heading %}
          <h1 class="display-4 fw-bold mb-3 text-white">{{ section.settings.heading }}</h1>
        {% endif %}
        {% if section.settings.subheading %}
          <p class="lead mb-4 text-white-50">{{ section.settings.subheading }}</p>
        {% endif %}
        {% if section.settings.btn_text and section.settings.btn_link %}
          <a href="{{ section.settings.btn_link }}" class="btn btn-primary btn-lg px-4">{{ section.settings.btn_text }}</a>
        {% endif %}
      </div>
    </div>
  </div>
</section>

<style>
#jw-section-{{ section.id }} {
  min-height: {{ section.settings.min_height | default(450) }}px;
}
</style>

{% rules %}
{
  "name": "Hero Banner",
  "settings": [
    { "type": "text", "id": "heading", "label": "Main Heading", "default": "Next-Gen Digital Commerce" },
    { "type": "textarea", "id": "subheading", "label": "Subheading", "default": "Elevate your storefront experience." },
    { "type": "text", "id": "btn_text", "label": "Button Label", "default": "Shop New Arrivals" },
    { "type": "url", "id": "btn_link", "label": "Button URL", "default": "/collections/all" }
  ],
  "presets": [
    {
      "name": "Hero Banner",
      "settings": {
        "heading": "Next-Gen Digital Commerce",
        "subheading": "Elevate your storefront experience.",
        "btn_text": "Shop New Arrivals",
        "btn_link": "/collections/all"
      }
    }
  ]
}
{% endrules %}
```

### Installation
Save the generated code as `sections/[section_name].jw` in your theme folder. It will instantly appear in the JoonWeb visual editor sidebar for merchants to add and customize!

---

#### Build JoonWeb Section with Claude

##### Overview & Claude Setup

Anthropic's **Claude 3.5 Sonnet** offers industry-leading reasoning for structural code generation, responsive Bootstrap 5.3 markup, and JSON schema formatting.

By linking Claude to the official **`jw-theme-sections`** skill, you can generate complete, error-free `.jw` templates that adhere strictly to JoonWeb's storefront architecture.

---

### Quick Launch (1-Click Pre-Loaded Prompt)
[**⚡ Launch in Claude with Pre-Loaded Prompt**](https://claude.ai/new?q=You%20are%20an%20Expert%20JoonWeb%20Theme%20Developer.%20Follow%20the%20official%20JoonWeb%20section%20specifications%20at%20https%3A%2F%2Fjoonweb.dev%2Fskills%2Fjw-theme-sections%2FSKILL.md%20to%20build%20a%20production-ready%20.jw%20section.)

Claude natively supports instant prompt pre-loading via URL parameter (`https://claude.ai/new?q=...`), allowing you to start generating sections in one click.

### Integrating the Skill into Claude Projects
1. Open [Claude.ai](https://claude.ai) and navigate to **Projects**.
2. Create or open your JoonWeb development project.
3. Under **Project Knowledge**, add a reference or paste the contents of:
   `https://joonweb.dev/skills/jw-theme-sections/SKILL.md`
4. Now, any section generation prompt in your project will automatically follow official JoonWeb guidelines.

##### Claude Prompt Template

Copy and paste this prompt directly into your Claude chat:

```markdown
Please review the official JoonWeb Theme Development Skill:
https://joonweb.dev/skills/jw-theme-sections/SKILL.md

Generate a complete, production-ready `.jw` section for: [SECTION_NAME].

Architecture Guidelines:
1. Top Comment: {# Copy and paste this code directly into the JoonWeb Theme Editor (.jw file) #}
2. File Order: Variables {% set %} -> <style> (Scoped CSS MUST come BEFORE <section>) -> <section> (Outer HTML container) -> <script> -> {# Do not change if you don't know #} -> {% rules %}.
3. Outer Wrapper: <section id="jw-section-{{ section.id }}" class="xx background{{ sc }} ..." data-xx="1" data-bl="{{ site ? 0 : 1 }}" style="...">.
4. Conditionals: Use != '' (never != blank). Loops use {% for %}.
5. Scoped CSS: Scope all rules under {{ S }} with builder overrides {{ S }}[data-bl="1"].
6. Editable Blocks: Use data-jw-block.
7. Schema & Presets: ONLY valid types (radio yes/no, quickEditor, text, image_picker, range). Append {"type": "themes"} and {"type": "apps"} to schema blocks. NEVER include themes or apps in presets.
8. E-Commerce Elements: Use ProductFeed, JWCart.add, cart, and site.currency where applicable.
9. Clean Comments: No unnecessary, bulky decorative comments.
```

##### Claude Example Prompts & Scenarios

#### 1. Interactive Product Grid with Live Ajax Drawer
```text
Generate a Featured Product Grid section (.jw) for an online jewelry store:
- Collection picker and 4 to 8 products slider
- Responsive 2 columns on mobile, 4 columns on desktop
- Product card showing featured image, title, sale price, MRP strikethrough, and discount badge
- Instant Ajax Add to Cart button triggering JWCart.add(variantId, 1, this)
- Scoped CSS for card hover lift and smooth transitions
- Populated default presets with 4 demo products
```

#### 2. Sticky Announcement Bar with Coupon Badge
```text
Generate a sticky top Announcement Bar section (.jw) with:
- Background and text color pickers
- Marquee ticker animation toggle
- Promotional text message with clickable link
- Coupon code badge with 1-click copy script
- Dismiss close button with session storage memory
- Scoped CSS for ticker marquee animation
- Populated default presets with free shipping promo
```

##### Key Technical Rules for Claude Outputs

When validating Claude's generated `.jw` code, verify the following standards:

1. **Pure JW Syntax**: Conditionals must use `{% if %}`, `{% elseif %}`, `{% else %}`, `{% endif %}`. Brackets around conditions `(x == y)` should be avoided.
2. **Bootstrap 5.3 Only**: Layout must rely entirely on Bootstrap 5.3 grid (`row`, `col-*`), utilities, and Bootstrap Icons (`bi bi-*`). Tailwind CSS is never used inside `.jw` storefront sections.
3. **Block Rendering**: Blocks must be rendered via:
   ```html
   {% switch block.type %}
     {% default %}
       {{ render_block(block) }}
   {% endswitch %}
   ```
4. **Populated Presets**: The `presets` array in `{% rules %}` must contain full default values and block configurations so the section works out-of-the-box.

---

#### Build JoonWeb Section with Cursor

##### Overview & 1-Click Installation in Cursor

**Cursor AI** allows you to scaffold, edit, and refactor `.jw` sections directly inside your local development workspace using inline chat and Composer.

To make Cursor understand JoonWeb architecture and activate the **`@jw-theme`** command, external developers must install the skill locally into their workspace.

---

### Step 1: 1-Click Skill Installation (Terminal)

Run this single command in the root folder of your theme repository:

```bash
mkdir -p .cursor/rules && curl -s https://joonweb.dev/skills/jw-theme-sections/SKILL.md > .cursor/rules/jw-theme.mdc
```

This immediately downloads the official 1,000+ line JoonWeb Theme Skill into `.cursor/rules/jw-theme.mdc`. Cursor v0.42+ will automatically index the file, enabling the **`@jw-theme`** symbol across Composer and Chat without needing to restart!

---

### Alternative Installation Methods

#### For AI Agents (Google Antigravity, Windsurf, Copilot Workspace):
```bash
mkdir -p .agents/skills/jw-theme-sections && curl -s https://joonweb.dev/skills/jw-theme-sections/SKILL.md > .agents/skills/jw-theme-sections/SKILL.md
```

#### For Legacy Universal `.cursorrules`:
```bash
curl -s https://joonweb.dev/skills/jw-theme-sections/SKILL.md > .cursorrules
```

##### Cursor In-Editor Commands & Composer Prompts

Once `.cursorrules` is set up, you can command Cursor directly in **Composer (Cmd+I / Ctrl+I)** or **Chat (Cmd+L / Ctrl+L)**:

#### Scaffold a New Section
```text
@jw-theme Generate a new sections/customer-reviews.jw section with 5-star ratings, avatar image picker, quote block, and responsive 3-column Bootstrap card layout with populated presets.
```

#### Add Ajax Add-to-Cart to Existing Cards
```text
@jw-theme Update the product card button in this .jw file to use JWCart.add(variantId, 1, this) with a loading spinner state on click.
```

#### Add Settings to Rules Schema
```text
@jw-theme Add background color picker, padding top/bottom range sliders (20px to 120px), and an alignment select dropdown to the {% rules %} schema.
```

#### Build Storefront Header with Live Search (/suggestions.json)
```text
@jw-theme Generate a sticky header.jw section with brand logo, nav links, cart count badge, and debounced predictive search calling /suggestions.json?q={query}&limit=8 displaying products, collections, and blog articles.
```

---


## Admin API

### Overview

#### Admin API Overview & Authentication

##### Understanding the JoonWeb Admin REST API

The **JoonWeb Admin REST API** allows external applications and embedded iframe apps to interact with a JoonWeb merchant store. Using standard HTTP methods (`GET`, `POST`, `PUT`, `DELETE`), you can manage products, collections, orders, customers, themes, webhooks, discounts, checkouts, forms, and metafields.

### API Versioning & Base URL
All Admin API requests are versioned and routed through the merchant store domain:

```http
https://{yoursite}.myjoonweb.com/api/admin/26.0/{resource}
```

* **`{yoursite}`**: The merchant's JoonWeb store subdomain.
* **`26.0`**: Current API version endpoint.

### Required Request Headers
Every request must include the following headers:

| Header | Value | Description |
| - | - | - |
| `X-Joonweb-Access-Token` | `YOUR_ACCESS_TOKEN` | Permanent OAuth access token retrieved during OAuth handshake. |
| `Content-Type` | `application/json` | Required for `POST` and `PUT` request bodies. |

##### Official SDKs & Packages

JoonWeb provides native SDKs to simplify authentication, API calls, and embedded UI development across different tech stacks:

### 1. PHP SDK (`joonweb/joonweb-sdk`)
Install natively via Composer for backend PHP applications:
```bash
composer require joonweb/joonweb-sdk
```

### 2. Node.js SDK (`@joonweb/joonweb-sdk`)
Official Node.js SDK for server-side API requests:
```bash
npm install @joonweb/joonweb-sdk
```

### 3. React SDK (`@joonweb/react`)
Professional React UI SDK for building native-looking JoonWeb app user interfaces:
```bash
npm install @joonweb/react
```

### 4. App Bridge Packages
* **React App Bridge**: `npm install @joonweb/app-bridge-react` — Uses `<JoonwebProvider>` and `useAppBridge()` for embedded React UIs.
* **Node App Bridge**: `npm install @joonweb/app-bridge-node` — Middleware (`requireAppBridgeSession()`) for Express backend session verification.

##### OAuth Access Token Handshake

To authenticate Admin API calls, exchange your temporary authorization code for a permanent access token:

```http
POST https://{yoursite}.myjoonweb.com/api/admin/26.0/oauth/access_token
Content-Type: application/json

{
  "client_id": "jw_client_xxxxxxxx",
  "client_secret": "jw_secret_xxxxxxxx",
  "code": "auth_code_xxxxxxxx"
}
```

**Expected Response (200 OK)**:
```json
{
  "access_token": "jw_at_xxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "read_products,write_products"
}
```

##### What's Next?

- 🛍️ **[Products API Reference](/admin-api/products/products-reference)** — Explore product catalog endpoints.
- 📦 **[Orders API Reference](/admin-api/orders/orders-reference)** — Manage store orders.
- 🌐 **[App Bridge Component Guide](/apps/app-bridge/app-bridge-overview)** — Learn native UI components & modals.

---

#### Getting Started with JoonWeb CLI

##### Overview

The **JoonWeb CLI** (`joonweb`) is the official command-line interface for building, testing, and managing JoonWeb applications and theme extensions.

### Global Options
| Flag | Description |
| - | - |
| `-v, -V, --version` | Display current CLI version |
| `-d, --debug` | Enable verbose debug output (`DEBUG=true`) |

##### Installation

Install `@joonweb/cli` globally via npm:

```bash
npm install -g @joonweb/cli
```

To check your installed version, run:

```bash
joonweb -v
```

##### Account & Authentication Commands

### `joonweb login` 
Logs in to your JoonWeb Technology Partner account.

```bash
joonweb login
```

* **Options**:
  * `--shop <domain>`: Specify a shop domain directly.
* **Behavior**: Opens a browser window requesting Partner OAuth authorization.

---

### `joonweb whoami` 
Shows current login status, Partner organization, and active store session.

```bash
joonweb whoami
```

---

### `joonweb logout` 
Logs out and clears cached credentials from your local machine.

```bash
joonweb logout
```

---

### `joonweb update` (Alias: `joonweb upgrade`)
Updates the JoonWeb CLI to the latest version.

```bash
joonweb update
```

---

### `joonweb uninstall` (Alias: `joonweb remove`)
Uninstalls the JoonWeb CLI completely from your system.

```bash
joonweb uninstall
```

##### What's Next?

- 🛠️ **[CLI Command Reference](/joonweb-cli/commands/command-reference)** — Learn all `joonweb app` subcommands.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Step-by-step app creation tutorial.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/joonweb-cli/configuration/app-manifest)** — Complete configuration schema.

---

#### Ajax API Overview & Authentication

##### What is the JoonWeb Ajax API?

The **JoonWeb Ajax API** enhances theme interactivity for sites and stores built on JoonWeb.com.

It is a **tokenless, public API** designed for use in JoonWeb themes (`.jw` templates) and embedded app extensions. It enables real-time, seamless user experiences without full page reloads.

### Core Capabilities:
- 🛒 **Cart & Drawer Cart Management**: Add products/variants, update quantities, remove items, clear cart, and fetch live cart JSON.
- 🔍 **Predictive Search & Suggestions**: Instant search for products, articles, pages, and collections as users type.
- 🤖 **Product Recommendations**: Retrieve weighted algorithmic recommendations (category, collections, tags) or fallback products.
- 🔄 **Section & Block Reloading**: Render and reload individual `.jw` template sections on the fly without refreshing the page.
- ⚡ **Ajax Pagination & Infinite Scroll**: Load next product grid pages dynamically.

##### 🔐 Authentication & Session Scoping

🟢 **Public / Tokenless API**:  
**No Admin access token or API key is required.**

- The Ajax API is session-based and operates within the context of the active storefront visitor session (cookie-based).
- Works for both guest visitors and logged-in customers.
- Safe for use directly inside client-side JavaScript (`fetch()`, `Axios`, `XMLHttpRequest`).

##### ⚠️ Standard HTTP Status & Error Codes

| Status Code | Title | Description |
| - | - | - |
| `200 OK` | Success | Request completed successfully. |
| `400 Bad Request` | Invalid Request | Invalid parameters or missing session payload. |
| `404 Not Found` | Resource Missing | Product, variant, or item not found in cart. |
| `422 Unprocessable Entity` | Out of Stock | Requested quantity exceeds available inventory. |
| `429 Too Many Requests` | Rate Limited | Exceeded allowed requests per minute. |

---


### OAuth

#### OAuth Endpoints

##### Overview

### OAuth

Manage authentication and token generation.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### Exchange access token

**Method:** `POST`
**Path:** `/api/admin/26.0/oauth/access_token`

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "oauth": {
        "id": 104593,
        "client_id": "example_client_id",
        "client_secret": "example_client_secret",
        "code": "example_code",
        "created_at": "2026-08-25T16:23:32Z",
        "updated_at": "2026-08-25T16:23:32Z"
    }
}
```

**Description**: Exchange authorization code for a permanent access token.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### App Billing

#### App Billing Endpoints

##### Overview

### App Billing

Handle app monetization via one-time charges and subscriptions.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### Create one-time charge

**Method:** `POST`
**Path:** `/api/admin/26.0/create_app_billing`

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "charge": {
        "merchant_id": 104593,
        "price": 19.989999999999998436805981327779591083526611328125,
        "install_id": 104593,
        "pack_id": 104593,
        "name": "example_name",
        "return_url": "example_return_url",
        "test": true
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "app_billing": {
        "id": 4092,
        "name": "Pro Plan",
        "price": 29.989999999999998436805981327779591083526611328125,
        "status": "active",
        "return_url": "https:\/\/yourapp.com\/billing\/callback",
        "billing_on": "2026-09-26T11:31:04+02:00",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "test": true
    }
}
```

**Description**: Create one-time app charge.

##### Get one-time charge

**Method:** `GET`
**Path:** `/api/admin/26.0/app_billings/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "app_billing": {
        "id": 4092,
        "name": "Pro Plan",
        "price": 29.989999999999998436805981327779591083526611328125,
        "status": "active",
        "return_url": "https:\/\/yourapp.com\/billing\/callback",
        "billing_on": "2026-09-26T11:31:04+02:00",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "test": true
    }
}
```

**Description**: Retrieve details of a one-time charge.

##### Create subscription

**Method:** `POST`
**Path:** `/api/admin/26.0/recurring_application_charges`

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "recurring_charge": {
        "merchant_id": 104593,
        "price": 19.989999999999998436805981327779591083526611328125,
        "install_id": 104593,
        "pack_id": 104593,
        "name": "example_name",
        "return_url": "example_return_url",
        "test": true
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "recurring_application_charge": {
        "id": 4092,
        "name": "Pro Plan",
        "price": 29.989999999999998436805981327779591083526611328125,
        "status": "active",
        "return_url": "https:\/\/yourapp.com\/billing\/callback",
        "billing_on": "2026-09-26T11:31:04+02:00",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "test": true
    }
}
```

**Description**: Create recurring subscription.

##### Get subscription

**Method:** `GET`
**Path:** `/api/admin/26.0/recurring_application_charges/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "recurring_application_charge": {
        "id": 4092,
        "name": "Pro Plan",
        "price": 29.989999999999998436805981327779591083526611328125,
        "status": "active",
        "return_url": "https:\/\/yourapp.com\/billing\/callback",
        "billing_on": "2026-09-26T11:31:04+02:00",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "test": true
    }
}
```

**Description**: Retrieve details of recurring subscription.

##### Activate subscription

**Method:** `POST`
**Path:** `/api/admin/26.0/recurring_application_charges/{id}/activate`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "recurring_application_charge": {
        "id": 4092,
        "name": "Pro Plan",
        "price": 29.989999999999998436805981327779591083526611328125,
        "status": "active",
        "return_url": "https:\/\/yourapp.com\/billing\/callback",
        "billing_on": "2026-09-26T11:31:04+02:00",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "test": true
    }
}
```

**Description**: Activate the recurring subscription.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Checkouts

#### Checkouts Endpoints

##### Overview

### Checkouts

Manage shopping carts and checkout processes.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List checkouts

**Method:** `GET`
**Path:** `/api/admin/26.0/checkouts`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "checkouts": [
        {
            "id": 84092,
            "token": "chk_8492058abdef",
            "cart_token": "crt_893049",
            "email": "jane.doe@example.com",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "subtotal_price": 149.990000000000009094947017729282379150390625,
            "total_price": 159.990000000000009094947017729282379150390625,
            "total_tax": 0,
            "taxes_included": false,
            "currency": "USD",
            "line_items": [
                {
                    "id": 48291,
                    "variant_id": 4920,
                    "product_id": 104593,
                    "title": "Premium Wireless Headphones",
                    "quantity": 1,
                    "sku": "ATH-BLK-01",
                    "price": 149.990000000000009094947017729282379150390625,
                    "vendor": "AudioTech",
                    "fulfillment_status": "unfulfilled",
                    "taxable": true
                }
            ],
            "shipping_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            },
            "shipping_line": {
                "id": 102,
                "title": "Standard Shipping",
                "price": 10,
                "code": "Standard"
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List ongoing checkouts.

##### Count checkouts

**Method:** `GET`
**Path:** `/api/admin/26.0/checkouts/count`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "count": 12
}
```

**Description**: Count total checkouts.

##### Get checkout

**Method:** `GET`
**Path:** `/api/admin/26.0/checkouts/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "checkout": {
        "id": 84092,
        "token": "chk_8492058abdef",
        "cart_token": "crt_893049",
        "email": "jane.doe@example.com",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "subtotal_price": 149.990000000000009094947017729282379150390625,
        "total_price": 159.990000000000009094947017729282379150390625,
        "total_tax": 0,
        "taxes_included": false,
        "currency": "USD",
        "line_items": [
            {
                "id": 48291,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Premium Wireless Headphones",
                "quantity": 1,
                "sku": "ATH-BLK-01",
                "price": 149.990000000000009094947017729282379150390625,
                "vendor": "AudioTech",
                "fulfillment_status": "unfulfilled",
                "taxable": true
            }
        ],
        "shipping_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        },
        "shipping_line": {
            "id": 102,
            "title": "Standard Shipping",
            "price": 10,
            "code": "Standard"
        }
    }
}
```

**Description**: Retrieve details of a checkout.

##### Create checkout

**Method:** `POST`
**Path:** `/api/admin/26.0/checkouts`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `email` | `string` | [Optional] Customer email |
| `line_items` | `array` | [Required] Array of items in the checkout |
| `line_items[].variant_id` | `integer` | [Required] The ID of the product variant |
| `line_items[].quantity` | `integer` | [Required] The quantity to add |
| `shipping_address` | `object` | [Optional] Shipping address object |
| `shipping_address.first_name` | `string` | [Optional] First name |
| `shipping_address.last_name` | `string` | [Optional] Last name |
| `shipping_address.address1` | `string` | [Optional] Line 1 of the address |
| `shipping_address.city` | `string` | [Optional] City name |
| `shipping_address.zip` | `string` | [Optional] Postal/Zip code |
| `shipping_address.country` | `string` | [Optional] Country name or code |
| `billing_address` | `object` | [Optional] Billing address (same format as shipping_address) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "checkout": {
        "email": "customer@example.com",
        "line_items": [
            {
                "variant_id": 10245,
                "quantity": 2
            }
        ],
        "shipping_address": {
            "first_name": "John",
            "last_name": "Doe",
            "address1": "123 Main St",
            "city": "New York",
            "zip": "10001",
            "country": "US"
        }
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "checkout": {
        "id": 84092,
        "token": "chk_8492058abdef",
        "cart_token": "crt_893049",
        "email": "jane.doe@example.com",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "subtotal_price": 149.990000000000009094947017729282379150390625,
        "total_price": 159.990000000000009094947017729282379150390625,
        "total_tax": 0,
        "taxes_included": false,
        "currency": "USD",
        "line_items": [
            {
                "id": 48291,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Premium Wireless Headphones",
                "quantity": 1,
                "sku": "ATH-BLK-01",
                "price": 149.990000000000009094947017729282379150390625,
                "vendor": "AudioTech",
                "fulfillment_status": "unfulfilled",
                "taxable": true
            }
        ],
        "shipping_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        },
        "shipping_line": {
            "id": 102,
            "title": "Standard Shipping",
            "price": 10,
            "code": "Standard"
        }
    }
}
```

**Description**: Create a new checkout session.

##### Update checkout

**Method:** `PUT`
**Path:** `/api/admin/26.0/checkouts/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `email` | `string` | [Optional] Customer email |
| `line_items` | `array` | [Required] Array of items in the checkout |
| `line_items[].variant_id` | `integer` | [Required] The ID of the product variant |
| `line_items[].quantity` | `integer` | [Required] The quantity to add |
| `shipping_address` | `object` | [Optional] Shipping address object |
| `shipping_address.first_name` | `string` | [Optional] First name |
| `shipping_address.last_name` | `string` | [Optional] Last name |
| `shipping_address.address1` | `string` | [Optional] Line 1 of the address |
| `shipping_address.city` | `string` | [Optional] City name |
| `shipping_address.zip` | `string` | [Optional] Postal/Zip code |
| `shipping_address.country` | `string` | [Optional] Country name or code |
| `billing_address` | `object` | [Optional] Billing address (same format as shipping_address) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "checkout": {
        "email": "customer@example.com",
        "line_items": [
            {
                "variant_id": 10245,
                "quantity": 2
            }
        ],
        "shipping_address": {
            "first_name": "John",
            "last_name": "Doe",
            "address1": "123 Main St",
            "city": "New York",
            "zip": "10001",
            "country": "US"
        }
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "checkout": {
        "id": 84092,
        "token": "chk_8492058abdef",
        "cart_token": "crt_893049",
        "email": "jane.doe@example.com",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "subtotal_price": 149.990000000000009094947017729282379150390625,
        "total_price": 159.990000000000009094947017729282379150390625,
        "total_tax": 0,
        "taxes_included": false,
        "currency": "USD",
        "line_items": [
            {
                "id": 48291,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Premium Wireless Headphones",
                "quantity": 1,
                "sku": "ATH-BLK-01",
                "price": 149.990000000000009094947017729282379150390625,
                "vendor": "AudioTech",
                "fulfillment_status": "unfulfilled",
                "taxable": true
            }
        ],
        "shipping_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        },
        "shipping_line": {
            "id": 102,
            "title": "Standard Shipping",
            "price": 10,
            "code": "Standard"
        }
    }
}
```

**Description**: Update an ongoing checkout.

##### Complete checkout

**Method:** `POST`
**Path:** `/api/admin/26.0/checkouts/{id}/complete`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `email` | `string` | [Optional] Customer email |
| `line_items` | `array` | [Required] Array of items in the checkout |
| `line_items[].variant_id` | `integer` | [Required] The ID of the product variant |
| `line_items[].quantity` | `integer` | [Required] The quantity to add |
| `shipping_address` | `object` | [Optional] Shipping address object |
| `shipping_address.first_name` | `string` | [Optional] First name |
| `shipping_address.last_name` | `string` | [Optional] Last name |
| `shipping_address.address1` | `string` | [Optional] Line 1 of the address |
| `shipping_address.city` | `string` | [Optional] City name |
| `shipping_address.zip` | `string` | [Optional] Postal/Zip code |
| `shipping_address.country` | `string` | [Optional] Country name or code |
| `billing_address` | `object` | [Optional] Billing address (same format as shipping_address) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "checkout": {
        "email": "customer@example.com",
        "line_items": [
            {
                "variant_id": 10245,
                "quantity": 2
            }
        ],
        "shipping_address": {
            "first_name": "John",
            "last_name": "Doe",
            "address1": "123 Main St",
            "city": "New York",
            "zip": "10001",
            "country": "US"
        }
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "checkout": {
        "id": 84092,
        "token": "chk_8492058abdef",
        "cart_token": "crt_893049",
        "email": "jane.doe@example.com",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "subtotal_price": 149.990000000000009094947017729282379150390625,
        "total_price": 159.990000000000009094947017729282379150390625,
        "total_tax": 0,
        "taxes_included": false,
        "currency": "USD",
        "line_items": [
            {
                "id": 48291,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Premium Wireless Headphones",
                "quantity": 1,
                "sku": "ATH-BLK-01",
                "price": 149.990000000000009094947017729282379150390625,
                "vendor": "AudioTech",
                "fulfillment_status": "unfulfilled",
                "taxable": true
            }
        ],
        "shipping_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        },
        "shipping_line": {
            "id": 102,
            "title": "Standard Shipping",
            "price": 10,
            "code": "Standard"
        }
    }
}
```

**Description**: Mark a checkout as completed.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Collections

#### Collections Endpoints

##### Overview

### Collections

Manage product collections and categories.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List collections

**Method:** `GET`
**Path:** `/api/admin/26.0/collections`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |
| `search` | `string` | [Optional] Search in title |
| `status` | `string` | [Optional] Filter by status |
| `handle` | `string` | [Optional] Filter by handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "collections": [
        {
            "id": 5032,
            "handle": "summer-collection",
            "title": "Summer Collection 2026",
            "description": "Get ready for the heat with our new arrivals.",
            "cover": "https:\/\/cdn.joonweb.com\/images\/summer-banner.jpg",
            "status": "public",
            "sort_order": "manual",
            "rules": [
                {
                    "column": "tag",
                    "relation": "equals",
                    "condition": "summer"
                }
            ],
            "products_count": 45,
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all collections.

##### Count collections

**Method:** `GET`
**Path:** `/api/admin/26.0/collections/count`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |
| `search` | `string` | [Optional] Search in title |
| `status` | `string` | [Optional] Filter by status |
| `handle` | `string` | [Optional] Filter by handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "count": 156
}
```

**Description**: Count total collections.

##### Get collection

**Method:** `GET`
**Path:** `/api/admin/26.0/collections/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "collection": {
        "id": 5032,
        "handle": "summer-collection",
        "title": "Summer Collection 2026",
        "description": "Get ready for the heat with our new arrivals.",
        "cover": "https:\/\/cdn.joonweb.com\/images\/summer-banner.jpg",
        "status": "public",
        "sort_order": "manual",
        "rules": [
            {
                "column": "tag",
                "relation": "equals",
                "condition": "summer"
            }
        ],
        "products_count": 45,
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Retrieve a specific collection.

##### List collection products

**Method:** `GET`
**Path:** `/api/admin/26.0/collections/{id}/products`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "collection": {
        "id": 5032,
        "handle": "summer-collection",
        "title": "Summer Collection 2026",
        "description": "Get ready for the heat with our new arrivals.",
        "cover": "https:\/\/cdn.joonweb.com\/images\/summer-banner.jpg",
        "status": "public",
        "sort_order": "manual",
        "rules": [
            {
                "column": "tag",
                "relation": "equals",
                "condition": "summer"
            }
        ],
        "products_count": 45,
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Retrieve products assigned to a collection.

##### Create collection

**Method:** `POST`
**Path:** `/api/admin/26.0/collections`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `title` | `string` | [Required] The title of the collection |
| `description` | `string` | [Optional] HTML description |
| `status` | `string` | [Optional] Status: public or draft |
| `sort_order` | `string` | [Optional] manual, best-selling, alpha-asc, etc. |
| `rules` | `array` | [Optional] Array of smart collection rules |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "collection": {
        "title": "example_title",
        "body_html": "example_body_html",
        "handle": "example_handle",
        "status": "active",
        "type": "example_type",
        "image": {}
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "collection": {
        "id": 5032,
        "handle": "summer-collection",
        "title": "Summer Collection 2026",
        "description": "Get ready for the heat with our new arrivals.",
        "cover": "https:\/\/cdn.joonweb.com\/images\/summer-banner.jpg",
        "status": "public",
        "sort_order": "manual",
        "rules": [
            {
                "column": "tag",
                "relation": "equals",
                "condition": "summer"
            }
        ],
        "products_count": 45,
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Create a new collection.

##### Update collection

**Method:** `PUT`
**Path:** `/api/admin/26.0/collections/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `title` | `string` | [Required] The title of the collection |
| `description` | `string` | [Optional] HTML description |
| `status` | `string` | [Optional] Status: public or draft |
| `sort_order` | `string` | [Optional] manual, best-selling, alpha-asc, etc. |
| `rules` | `array` | [Optional] Array of smart collection rules |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "collection": []
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "collection": {
        "id": 5032,
        "handle": "summer-collection",
        "title": "Summer Collection 2026",
        "description": "Get ready for the heat with our new arrivals.",
        "cover": "https:\/\/cdn.joonweb.com\/images\/summer-banner.jpg",
        "status": "public",
        "sort_order": "manual",
        "rules": [
            {
                "column": "tag",
                "relation": "equals",
                "condition": "summer"
            }
        ],
        "products_count": 45,
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Update an existing collection.

##### Delete collection

**Method:** `DELETE`
**Path:** `/api/admin/26.0/collections/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete a collection.

##### List collection metafields

**Method:** `GET`
**Path:** `/api/admin/26.0/collections/{id}/metafields.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafields": [
        {
            "id": 8492,
            "namespace": "global",
            "key": "title_tag",
            "value": "Buy Premium Headphones Online",
            "value_type": "string",
            "description": "SEO Title Tag",
            "owner_id": 104593,
            "owner_resource": "product",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List collection metafields.

##### Create collection metafield

**Method:** `POST`
**Path:** `/api/admin/26.0/collections/{id}/metafields.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `namespace` | `string` | [Required] Grouping namespace |
| `key` | `string` | [Required] Metafield key |
| `value` | `string` | [Required] Metafield value |
| `value_type` | `string` | [Required] string, integer, json, etc. |
| `description` | `string` | [Optional] Description of the metafield |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafield": {
        "id": 8492,
        "namespace": "global",
        "key": "title_tag",
        "value": "Buy Premium Headphones Online",
        "value_type": "string",
        "description": "SEO Title Tag",
        "owner_id": 104593,
        "owner_resource": "product",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Create collection metafield.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Customers

#### Customers Endpoints

##### Overview

### Customers

Manage customer accounts, addresses, and orders.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List customers

**Method:** `GET`
**Path:** `/api/admin/26.0/customers`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |
| `search` | `string` | [Optional] Search by name or email |
| `email` | `string` | [Optional] Filter by email address |
| `phone` | `string` | [Optional] Filter by phone number |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "customers": [
        {
            "id": 84920,
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@example.com",
            "phone": "+15550198273",
            "accepts_marketing": true,
            "orders_count": 4,
            "total_spent": 549.9600000000000363797880709171295166015625,
            "currency": "USD",
            "state": "enabled",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "default_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all customers.

##### Get customer

**Method:** `GET`
**Path:** `/api/admin/26.0/customers/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "customer": {
        "id": 84920,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com",
        "phone": "+15550198273",
        "accepts_marketing": true,
        "orders_count": 4,
        "total_spent": 549.9600000000000363797880709171295166015625,
        "currency": "USD",
        "state": "enabled",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "default_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    }
}
```

**Description**: Retrieve a specific customer.

##### Create customer

**Method:** `POST`
**Path:** `/api/admin/26.0/customers`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `first_name` | `string` | [Optional] Customer first name |
| `last_name` | `string` | [Optional] Customer last name |
| `email` | `string` | [Required for POST] Customer email address |
| `phone` | `string` | [Optional] Customer phone number |
| `accepts_marketing` | `boolean` | [Optional] Marketing opt-in |
| `default_address` | `object` | [Optional] Address object (address1, city, country, etc.) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "customer": {
        "email": "user@example.com",
        "username": "example_username",
        "name": "example_name",
        "mobile": "example_mobile",
        "password": "example_password",
        "avatar": "example_avatar",
        "data": {},
        "status": "active",
        "type": "example_type"
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "customer": {
        "id": 84920,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com",
        "phone": "+15550198273",
        "accepts_marketing": true,
        "orders_count": 4,
        "total_spent": 549.9600000000000363797880709171295166015625,
        "currency": "USD",
        "state": "enabled",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "default_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    }
}
```

**Description**: Create a new customer.

##### Update customer

**Method:** `PUT`
**Path:** `/api/admin/26.0/customers/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `first_name` | `string` | [Optional] Customer first name |
| `last_name` | `string` | [Optional] Customer last name |
| `email` | `string` | [Required for POST] Customer email address |
| `phone` | `string` | [Optional] Customer phone number |
| `accepts_marketing` | `boolean` | [Optional] Marketing opt-in |
| `default_address` | `object` | [Optional] Address object (address1, city, country, etc.) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "customer": []
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "customer": {
        "id": 84920,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com",
        "phone": "+15550198273",
        "accepts_marketing": true,
        "orders_count": 4,
        "total_spent": 549.9600000000000363797880709171295166015625,
        "currency": "USD",
        "state": "enabled",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "default_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    }
}
```

**Description**: Update a customer profile.

##### Delete customer

**Method:** `DELETE`
**Path:** `/api/admin/26.0/customers/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete a customer profile.

##### List customer orders

**Method:** `GET`
**Path:** `/api/admin/26.0/customers/{id}/orders`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "orders": [
        {
            "id": 104938,
            "email": "jane.doe@example.com",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "number": 1004,
            "order_number": "#1004",
            "total_price": 149.990000000000009094947017729282379150390625,
            "subtotal_price": 149.990000000000009094947017729282379150390625,
            "total_weight": 0.450000000000000011102230246251565404236316680908203125,
            "total_tax": 0,
            "taxes_included": false,
            "currency": "USD",
            "financial_status": "paid",
            "fulfillment_status": "unfulfilled",
            "total_discounts": 0,
            "total_line_items_price": 149.990000000000009094947017729282379150390625,
            "customer": {
                "id": 84920,
                "first_name": "Jane",
                "last_name": "Doe",
                "email": "jane.doe@example.com",
                "phone": "+15550198273",
                "accepts_marketing": true,
                "orders_count": 4,
                "total_spent": 549.9600000000000363797880709171295166015625,
                "currency": "USD",
                "state": "enabled",
                "created_at": "2026-08-27T11:31:04+02:00",
                "updated_at": "2026-08-27T11:31:04+02:00",
                "default_address": {
                    "id": 10293,
                    "first_name": "Jane",
                    "last_name": "Doe",
                    "company": "Doe Tech",
                    "address1": "123 Developer Way",
                    "address2": "Suite 100",
                    "city": "San Francisco",
                    "province": "California",
                    "country": "United States",
                    "zip": "94105",
                    "phone": "+15550198273",
                    "province_code": "CA",
                    "country_code": "US",
                    "country_name": "United States",
                    "default": true
                }
            },
            "line_items": [
                {
                    "id": 48291,
                    "variant_id": 4920,
                    "product_id": 104593,
                    "title": "Premium Wireless Headphones",
                    "quantity": 1,
                    "sku": "ATH-BLK-01",
                    "price": 149.990000000000009094947017729282379150390625,
                    "vendor": "AudioTech",
                    "fulfillment_status": "unfulfilled",
                    "taxable": true
                }
            ],
            "billing_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            },
            "shipping_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: Retrieve orders for a customer.

##### List customer addresses

**Method:** `GET`
**Path:** `/api/admin/26.0/customers/{id}/addresses`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "addresses": [
        {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    ]
}
```

**Description**: List addresses for a customer.

##### List customer metafields

**Method:** `GET`
**Path:** `/api/admin/26.0/customers/{id}/metafields.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "customer": {
        "id": 84920,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com",
        "phone": "+15550198273",
        "accepts_marketing": true,
        "orders_count": 4,
        "total_spent": 549.9600000000000363797880709171295166015625,
        "currency": "USD",
        "state": "enabled",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "default_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    }
}
```

**Description**: List customer metafields.

##### Create customer metafield

**Method:** `POST`
**Path:** `/api/admin/26.0/customers/{id}/metafields.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `namespace` | `string` | [Required] Grouping namespace |
| `key` | `string` | [Required] Metafield key |
| `value` | `string` | [Required] Metafield value |
| `value_type` | `string` | [Required] string, integer, json, etc. |
| `description` | `string` | [Optional] Description of the metafield |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "customer": {
        "id": 84920,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com",
        "phone": "+15550198273",
        "accepts_marketing": true,
        "orders_count": 4,
        "total_spent": 549.9600000000000363797880709171295166015625,
        "currency": "USD",
        "state": "enabled",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "default_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    }
}
```

**Description**: Create a customer metafield.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Discounts

#### Discounts Endpoints

##### Overview

### Discounts

Manage discount codes and promotions.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List discounts

**Method:** `GET`
**Path:** `/api/admin/26.0/discounts`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "discounts": [
        {
            "id": 40392,
            "code": "SUMMER26",
            "value": "20.0",
            "value_type": "percentage",
            "usage_limit": 100,
            "times_used": 45,
            "starts_at": "2026-08-27T11:31:04+02:00",
            "ends_at": null,
            "status": "active"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all discounts.

##### Get discount

**Method:** `GET`
**Path:** `/api/admin/26.0/discounts/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "discount": {
        "id": 40392,
        "code": "SUMMER26",
        "value": "20.0",
        "value_type": "percentage",
        "usage_limit": 100,
        "times_used": 45,
        "starts_at": "2026-08-27T11:31:04+02:00",
        "ends_at": null,
        "status": "active"
    }
}
```

**Description**: Retrieve a single discount.

##### Get discount by code

**Method:** `GET`
**Path:** `/api/admin/26.0/discounts/code/{code}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `code` | `string` | [Required] The discount code |
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "discount": {
        "id": 40392,
        "code": "SUMMER26",
        "value": "20.0",
        "value_type": "percentage",
        "usage_limit": 100,
        "times_used": 45,
        "starts_at": "2026-08-27T11:31:04+02:00",
        "ends_at": null,
        "status": "active"
    }
}
```

**Description**: Retrieve discount by coupon code.

##### Create discount

**Method:** `POST`
**Path:** `/api/admin/26.0/discounts`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `code` | `string` | [Required] Unique discount code |
| `value` | `float` | [Required] Discount value |
| `value_type` | `string` | [Required] percentage or fixed_amount |
| `usage_limit` | `integer` | [Optional] Max number of times can be used |
| `starts_at` | `string` | [Optional] ISO 8601 start date |
| `ends_at` | `string` | [Optional] ISO 8601 end date |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "discount": {
        "id": 40392,
        "code": "SUMMER26",
        "value": "20.0",
        "value_type": "percentage",
        "usage_limit": 100,
        "times_used": 45,
        "starts_at": "2026-08-27T11:31:04+02:00",
        "ends_at": null,
        "status": "active"
    }
}
```

**Description**: Create a new discount code.

##### Update discount

**Method:** `PUT`
**Path:** `/api/admin/26.0/discounts/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `code` | `string` | [Required] Unique discount code |
| `value` | `float` | [Required] Discount value |
| `value_type` | `string` | [Required] percentage or fixed_amount |
| `usage_limit` | `integer` | [Optional] Max number of times can be used |
| `starts_at` | `string` | [Optional] ISO 8601 start date |
| `ends_at` | `string` | [Optional] ISO 8601 end date |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "discount": {
        "id": 40392,
        "code": "SUMMER26",
        "value": "20.0",
        "value_type": "percentage",
        "usage_limit": 100,
        "times_used": 45,
        "starts_at": "2026-08-27T11:31:04+02:00",
        "ends_at": null,
        "status": "active"
    }
}
```

**Description**: Update an existing discount.

##### Delete discount

**Method:** `DELETE`
**Path:** `/api/admin/26.0/discounts/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete a discount.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Forms

#### Forms Endpoints

##### Overview

### Forms

Manage custom forms and submitted lead data.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List forms

**Method:** `GET`
**Path:** `/api/admin/26.0/forms`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "forms": [
        {
            "id": 402,
            "name": "Contact Us",
            "status": "public",
            "fields": [
                {
                    "name": "firstName",
                    "type": "text",
                    "label": "First Name",
                    "required": true
                },
                {
                    "name": "email",
                    "type": "email",
                    "label": "Email",
                    "required": true
                }
            ],
            "leads_count": 14,
            "created_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all custom forms.

##### Get form

**Method:** `GET`
**Path:** `/api/admin/26.0/forms/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "form": {
        "id": 402,
        "name": "Contact Us",
        "status": "public",
        "fields": [
            {
                "name": "firstName",
                "type": "text",
                "label": "First Name",
                "required": true
            },
            {
                "name": "email",
                "type": "email",
                "label": "Email",
                "required": true
            }
        ],
        "leads_count": 14,
        "created_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Retrieve a specific form structure.

##### Create form

**Method:** `POST`
**Path:** `/api/admin/26.0/forms`

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "form": {
        "title": "example_title",
        "description": "example_description",
        "fields": [],
        "conditions": [],
        "captcha": "example_captcha",
        "otp": "example_otp",
        "otp_data": {},
        "payment_data": {},
        "notification_email": "user@example.com",
        "notification_type": "example_notification_type",
        "submit_text": "example_submit_text",
        "action": {},
        "type": "example_type",
        "whitelist": [],
        "status": "active"
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "form": {
        "id": 402,
        "name": "Contact Us",
        "status": "public",
        "fields": [
            {
                "name": "firstName",
                "type": "text",
                "label": "First Name",
                "required": true
            },
            {
                "name": "email",
                "type": "email",
                "label": "Email",
                "required": true
            }
        ],
        "leads_count": 14,
        "created_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Create a new form.

##### Update form

**Method:** `PUT`
**Path:** `/api/admin/26.0/forms/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "form": []
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "form": {
        "id": 402,
        "name": "Contact Us",
        "status": "public",
        "fields": [
            {
                "name": "firstName",
                "type": "text",
                "label": "First Name",
                "required": true
            },
            {
                "name": "email",
                "type": "email",
                "label": "Email",
                "required": true
            }
        ],
        "leads_count": 14,
        "created_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Update an existing form.

##### Delete form

**Method:** `DELETE`
**Path:** `/api/admin/26.0/forms/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete a form.

##### List form leads

**Method:** `GET`
**Path:** `/api/admin/26.0/forms/{id}/leads`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "leads": [
        {
            "id": 1,
            "form_id": 402,
            "customer_id": 84920,
            "data": {
                "firstName": "Jane",
                "email": "jane.doe@example.com"
            },
            "created_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: Retrieve leads submitted for a form.

##### List all leads

**Method:** `GET`
**Path:** `/api/admin/26.0/leads`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "leads": [
        {
            "id": 1,
            "form_id": 402,
            "customer_id": 84920,
            "data": {
                "firstName": "Jane",
                "email": "jane.doe@example.com"
            },
            "created_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all leads across all forms.

##### Get lead

**Method:** `GET`
**Path:** `/api/admin/26.0/leads/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "leads": [
        {
            "id": 1,
            "form_id": 402,
            "customer_id": 84920,
            "data": {
                "firstName": "Jane",
                "email": "jane.doe@example.com"
            },
            "created_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: Retrieve details of a specific lead.

##### List customer leads

**Method:** `GET`
**Path:** `/api/admin/26.0/customers/{id}/leads`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "leads": [
        {
            "id": 1,
            "form_id": 402,
            "customer_id": 84920,
            "data": {
                "firstName": "Jane",
                "email": "jane.doe@example.com"
            },
            "created_at": "2026-08-27T11:31:04+02:00"
        }
    ]
}
```

**Description**: Retrieve leads submitted by customer.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Metafields (Core)

#### Metafields (Core) Endpoints

##### Overview

### Metafields (Core)

Manage metafield definitions and values globally.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List metafield definitions

**Method:** `GET`
**Path:** `/api/admin/26.0/metafield_definitions`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafield_definitions": [
        {
            "id": 593,
            "namespace": "global",
            "key": "title_tag",
            "name": "SEO Title Tag",
            "description": "Custom SEO Title",
            "type": "single_line_text_field",
            "owner_type": "PRODUCT",
            "validations": [
                {
                    "name": "min",
                    "value": 10
                },
                {
                    "name": "max",
                    "value": 60
                }
            ]
        }
    ]
}
```

**Description**: List metafield schema definitions.

##### Create metafield definition

**Method:** `POST`
**Path:** `/api/admin/26.0/metafield_definitions`

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "owner_type": "product",
    "namespace": "global",
    "key": "material",
    "type": "single_line_text_field",
    "label": "Material"
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "metafield_definition": {
        "id": 593,
        "namespace": "global",
        "key": "title_tag",
        "name": "SEO Title Tag",
        "description": "Custom SEO Title",
        "type": "single_line_text_field",
        "owner_type": "PRODUCT",
        "validations": [
            {
                "name": "min",
                "value": 10
            },
            {
                "name": "max",
                "value": 60
            }
        ]
    }
}
```

**Description**: Create metafield schema.

##### Delete metafield definition

**Method:** `DELETE`
**Path:** `/api/admin/26.0/metafield_definitions`

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete a metafield definition.

##### List metafield values

**Method:** `GET`
**Path:** `/api/admin/26.0/metafields`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafields": [
        {
            "id": 8492,
            "namespace": "global",
            "key": "title_tag",
            "value": "Buy Premium Headphones Online",
            "value_type": "string",
            "description": "SEO Title Tag",
            "owner_id": 104593,
            "owner_resource": "product",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all metafield values.

##### Create metafield value

**Method:** `POST`
**Path:** `/api/admin/26.0/metafields`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `namespace` | `string` | [Required] Grouping namespace |
| `key` | `string` | [Required] Metafield key |
| `value` | `string` | [Required] Metafield value |
| `value_type` | `string` | [Required] string, integer, json, etc. |
| `description` | `string` | [Optional] Description of the metafield |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "owner_type": "product",
    "owner_id": 104593,
    "namespace": "custom",
    "key": "material",
    "value": "Cotton"
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "metafield": {
        "id": 8492,
        "namespace": "global",
        "key": "title_tag",
        "value": "Buy Premium Headphones Online",
        "value_type": "string",
        "description": "SEO Title Tag",
        "owner_id": 104593,
        "owner_resource": "product",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Create a generic metafield value.

##### Update metafield value

**Method:** `PUT`
**Path:** `/api/admin/26.0/metafields/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `namespace` | `string` | [Required] Grouping namespace |
| `key` | `string` | [Required] Metafield key |
| `value` | `string` | [Required] Metafield value |
| `value_type` | `string` | [Required] string, integer, json, etc. |
| `description` | `string` | [Optional] Description of the metafield |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "value": "Updated Material"
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "metafield": {
        "id": 8492,
        "namespace": "global",
        "key": "title_tag",
        "value": "Buy Premium Headphones Online",
        "value_type": "string",
        "description": "SEO Title Tag",
        "owner_id": 104593,
        "owner_resource": "product",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Update a generic metafield value.

##### Delete metafield value

**Method:** `DELETE`
**Path:** `/api/admin/26.0/metafields/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete a metafield value.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Orders

#### Orders Endpoints

##### Overview

### Orders

Access and manage store orders.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List orders

**Method:** `GET`
**Path:** `/api/admin/26.0/orders`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |
| `status` | `string` | [Optional] Filter by status (open, closed, cancelled) |
| `financial_status` | `string` | [Optional] Filter by financial status (paid, pending) |
| `fulfillment_status` | `string` | [Optional] Filter by fulfillment (fulfilled, partial) |
| `customer_id` | `integer` | [Optional] Filter by customer ID |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "orders": [
        {
            "id": 104938,
            "email": "jane.doe@example.com",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "number": 1004,
            "order_number": "#1004",
            "total_price": 149.990000000000009094947017729282379150390625,
            "subtotal_price": 149.990000000000009094947017729282379150390625,
            "total_weight": 0.450000000000000011102230246251565404236316680908203125,
            "total_tax": 0,
            "taxes_included": false,
            "currency": "USD",
            "financial_status": "paid",
            "fulfillment_status": "unfulfilled",
            "total_discounts": 0,
            "total_line_items_price": 149.990000000000009094947017729282379150390625,
            "customer": {
                "id": 84920,
                "first_name": "Jane",
                "last_name": "Doe",
                "email": "jane.doe@example.com",
                "phone": "+15550198273",
                "accepts_marketing": true,
                "orders_count": 4,
                "total_spent": 549.9600000000000363797880709171295166015625,
                "currency": "USD",
                "state": "enabled",
                "created_at": "2026-08-27T11:31:04+02:00",
                "updated_at": "2026-08-27T11:31:04+02:00",
                "default_address": {
                    "id": 10293,
                    "first_name": "Jane",
                    "last_name": "Doe",
                    "company": "Doe Tech",
                    "address1": "123 Developer Way",
                    "address2": "Suite 100",
                    "city": "San Francisco",
                    "province": "California",
                    "country": "United States",
                    "zip": "94105",
                    "phone": "+15550198273",
                    "province_code": "CA",
                    "country_code": "US",
                    "country_name": "United States",
                    "default": true
                }
            },
            "line_items": [
                {
                    "id": 48291,
                    "variant_id": 4920,
                    "product_id": 104593,
                    "title": "Premium Wireless Headphones",
                    "quantity": 1,
                    "sku": "ATH-BLK-01",
                    "price": 149.990000000000009094947017729282379150390625,
                    "vendor": "AudioTech",
                    "fulfillment_status": "unfulfilled",
                    "taxable": true
                }
            ],
            "billing_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            },
            "shipping_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List orders with filtering options.

##### Get order details

**Method:** `GET`
**Path:** `/api/admin/26.0/orders/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "order": {
        "id": 104938,
        "email": "jane.doe@example.com",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "number": 1004,
        "order_number": "#1004",
        "total_price": 149.990000000000009094947017729282379150390625,
        "subtotal_price": 149.990000000000009094947017729282379150390625,
        "total_weight": 0.450000000000000011102230246251565404236316680908203125,
        "total_tax": 0,
        "taxes_included": false,
        "currency": "USD",
        "financial_status": "paid",
        "fulfillment_status": "unfulfilled",
        "total_discounts": 0,
        "total_line_items_price": 149.990000000000009094947017729282379150390625,
        "customer": {
            "id": 84920,
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@example.com",
            "phone": "+15550198273",
            "accepts_marketing": true,
            "orders_count": 4,
            "total_spent": 549.9600000000000363797880709171295166015625,
            "currency": "USD",
            "state": "enabled",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "default_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            }
        },
        "line_items": [
            {
                "id": 48291,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Premium Wireless Headphones",
                "quantity": 1,
                "sku": "ATH-BLK-01",
                "price": 149.990000000000009094947017729282379150390625,
                "vendor": "AudioTech",
                "fulfillment_status": "unfulfilled",
                "taxable": true
            }
        ],
        "billing_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        },
        "shipping_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    }
}
```

**Description**: Retrieve comprehensive details of an order, including line items and discounts.

##### Create order

**Method:** `POST`
**Path:** `/api/admin/26.0/orders`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `email` | `string` | [Optional] Customer email |
| `line_items` | `array` | [Required] Array of items in the checkout |
| `line_items[].variant_id` | `integer` | [Required] The ID of the product variant |
| `line_items[].quantity` | `integer` | [Required] The quantity to add |
| `shipping_address` | `object` | [Optional] Shipping address object |
| `shipping_address.first_name` | `string` | [Optional] First name |
| `shipping_address.last_name` | `string` | [Optional] Last name |
| `shipping_address.address1` | `string` | [Optional] Line 1 of the address |
| `shipping_address.city` | `string` | [Optional] City name |
| `shipping_address.zip` | `string` | [Optional] Postal/Zip code |
| `shipping_address.country` | `string` | [Optional] Country name or code |
| `billing_address` | `object` | [Optional] Billing address (same format as shipping_address) |
| `customer_id` | `integer` | [Optional] ID of existing customer |
| `financial_status` | `string` | [Optional] paid, pending, refunded |
| `currency` | `string` | [Optional] Currency code (e.g. USD) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "order": {
        "email": "customer@example.com",
        "customer_id": 5432,
        "financial_status": "paid",
        "currency": "USD",
        "line_items": [
            {
                "variant_id": 10245,
                "quantity": 1
            }
        ],
        "shipping_address": {
            "first_name": "John",
            "last_name": "Doe",
            "address1": "123 Main St",
            "city": "New York",
            "zip": "10001",
            "country": "US"
        }
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "order": {
        "id": 104938,
        "email": "jane.doe@example.com",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "number": 1004,
        "order_number": "#1004",
        "total_price": 149.990000000000009094947017729282379150390625,
        "subtotal_price": 149.990000000000009094947017729282379150390625,
        "total_weight": 0.450000000000000011102230246251565404236316680908203125,
        "total_tax": 0,
        "taxes_included": false,
        "currency": "USD",
        "financial_status": "paid",
        "fulfillment_status": "unfulfilled",
        "total_discounts": 0,
        "total_line_items_price": 149.990000000000009094947017729282379150390625,
        "customer": {
            "id": 84920,
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@example.com",
            "phone": "+15550198273",
            "accepts_marketing": true,
            "orders_count": 4,
            "total_spent": 549.9600000000000363797880709171295166015625,
            "currency": "USD",
            "state": "enabled",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "default_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            }
        },
        "line_items": [
            {
                "id": 48291,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Premium Wireless Headphones",
                "quantity": 1,
                "sku": "ATH-BLK-01",
                "price": 149.990000000000009094947017729282379150390625,
                "vendor": "AudioTech",
                "fulfillment_status": "unfulfilled",
                "taxable": true
            }
        ],
        "billing_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        },
        "shipping_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    }
}
```

**Description**: Create a new order programmatically.

##### Update order

**Method:** `PUT`
**Path:** `/api/admin/26.0/orders/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `email` | `string` | [Optional] Customer email |
| `line_items` | `array` | [Required] Array of items in the checkout |
| `line_items[].variant_id` | `integer` | [Required] The ID of the product variant |
| `line_items[].quantity` | `integer` | [Required] The quantity to add |
| `shipping_address` | `object` | [Optional] Shipping address object |
| `shipping_address.first_name` | `string` | [Optional] First name |
| `shipping_address.last_name` | `string` | [Optional] Last name |
| `shipping_address.address1` | `string` | [Optional] Line 1 of the address |
| `shipping_address.city` | `string` | [Optional] City name |
| `shipping_address.zip` | `string` | [Optional] Postal/Zip code |
| `shipping_address.country` | `string` | [Optional] Country name or code |
| `billing_address` | `object` | [Optional] Billing address (same format as shipping_address) |
| `customer_id` | `integer` | [Optional] ID of existing customer |
| `financial_status` | `string` | [Optional] paid, pending, refunded |
| `currency` | `string` | [Optional] Currency code (e.g. USD) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "order": {
        "email": "customer@example.com",
        "customer_id": 5432,
        "financial_status": "paid",
        "currency": "USD",
        "line_items": [
            {
                "variant_id": 10245,
                "quantity": 1
            }
        ],
        "shipping_address": {
            "first_name": "John",
            "last_name": "Doe",
            "address1": "123 Main St",
            "city": "New York",
            "zip": "10001",
            "country": "US"
        }
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "order": {
        "id": 104938,
        "email": "jane.doe@example.com",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "number": 1004,
        "order_number": "#1004",
        "total_price": 149.990000000000009094947017729282379150390625,
        "subtotal_price": 149.990000000000009094947017729282379150390625,
        "total_weight": 0.450000000000000011102230246251565404236316680908203125,
        "total_tax": 0,
        "taxes_included": false,
        "currency": "USD",
        "financial_status": "paid",
        "fulfillment_status": "unfulfilled",
        "total_discounts": 0,
        "total_line_items_price": 149.990000000000009094947017729282379150390625,
        "customer": {
            "id": 84920,
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@example.com",
            "phone": "+15550198273",
            "accepts_marketing": true,
            "orders_count": 4,
            "total_spent": 549.9600000000000363797880709171295166015625,
            "currency": "USD",
            "state": "enabled",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "default_address": {
                "id": 10293,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Doe Tech",
                "address1": "123 Developer Way",
                "address2": "Suite 100",
                "city": "San Francisco",
                "province": "California",
                "country": "United States",
                "zip": "94105",
                "phone": "+15550198273",
                "province_code": "CA",
                "country_code": "US",
                "country_name": "United States",
                "default": true
            }
        },
        "line_items": [
            {
                "id": 48291,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Premium Wireless Headphones",
                "quantity": 1,
                "sku": "ATH-BLK-01",
                "price": 149.990000000000009094947017729282379150390625,
                "vendor": "AudioTech",
                "fulfillment_status": "unfulfilled",
                "taxable": true
            }
        ],
        "billing_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        },
        "shipping_address": {
            "id": 10293,
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Doe Tech",
            "address1": "123 Developer Way",
            "address2": "Suite 100",
            "city": "San Francisco",
            "province": "California",
            "country": "United States",
            "zip": "94105",
            "phone": "+15550198273",
            "province_code": "CA",
            "country_code": "US",
            "country_name": "United States",
            "default": true
        }
    }
}
```

**Description**: Update an order.

##### Delete order

**Method:** `DELETE`
**Path:** `/api/admin/26.0/orders/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete an order.

##### List order metafields

**Method:** `GET`
**Path:** `/api/admin/26.0/orders/{id}/metafields.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafields": [
        {
            "id": 8492,
            "namespace": "global",
            "key": "title_tag",
            "value": "Buy Premium Headphones Online",
            "value_type": "string",
            "description": "SEO Title Tag",
            "owner_id": 104593,
            "owner_resource": "product",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List order metafields.

##### Create order metafield

**Method:** `POST`
**Path:** `/api/admin/26.0/orders/{id}/metafields.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `namespace` | `string` | [Required] Grouping namespace |
| `key` | `string` | [Required] Metafield key |
| `value` | `string` | [Required] Metafield value |
| `value_type` | `string` | [Required] string, integer, json, etc. |
| `description` | `string` | [Optional] Description of the metafield |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafield": {
        "id": 8492,
        "namespace": "global",
        "key": "title_tag",
        "value": "Buy Premium Headphones Online",
        "value_type": "string",
        "description": "SEO Title Tag",
        "owner_id": 104593,
        "owner_resource": "product",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Create an order metafield.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Products

#### Products Endpoints

##### Overview

### Products

Manage the product catalog.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List products

**Method:** `GET`
**Path:** `/api/admin/26.0/products`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |
| `collection_id` | `integer` | [Optional] Filter by collection ID |
| `vendor` | `string` | [Optional] Filter by vendor name |
| `product_type` | `string` | [Optional] Filter by product type |
| `available` | `boolean` | [Optional] Filter by availability (true/false) |
| `ids` | `string` | [Optional] Comma-separated list of product IDs |
| `handle` | `string` | [Optional] Filter by product handle |
| `min_stock` | `integer` | [Optional] Minimum inventory stock |
| `max_stock` | `integer` | [Optional] Maximum inventory stock |
| `search` | `string` | [Optional] Search in title or description |
| `inventory_status` | `string` | [Optional] Filter by status (available, out_of_stock) |
| `status` | `string` | [Optional] Filter by status (public, draft, private) |
| `min_price` | `float` | [Optional] Minimum price |
| `max_price` | `float` | [Optional] Maximum price |
| `fields` | `string` | [Optional] Comma-separated fields to return |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "products": [
        {
            "id": 104593,
            "handle": "premium-wireless-headphones",
            "title": "Premium Wireless Headphones",
            "description": "<p>Experience true audio freedom with our premium wireless headphones.<\/p>",
            "label": "Sale",
            "body_html": "<p>Experience true audio freedom with our premium wireless headphones.<\/p>",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "published_at": "2026-08-27T11:31:04+02:00",
            "vendor": "AudioTech",
            "product_type": "Electronics",
            "product_category": "Headphones",
            "status": "public",
            "tags": "audio, wireless, new",
            "inventory_quantity": 150,
            "available": true,
            "available_for_sale": true,
            "track_quantity": 1,
            "variants": [
                {
                    "id": 593821,
                    "variant_id": 4920,
                    "product_id": 104593,
                    "title": "Black \/ Standard",
                    "price": 149.990000000000009094947017729282379150390625,
                    "compare_at_price": 199.990000000000009094947017729282379150390625,
                    "sale_price": 149.990000000000009094947017729282379150390625,
                    "discount": 50,
                    "weight": 0.450000000000000011102230246251565404236316680908203125,
                    "weight_unit": "kg",
                    "sku": "ATH-BLK-01",
                    "is_trackable": true,
                    "track_quantity": true,
                    "inventory_quantity": 100,
                    "created_at": "2026-08-27T11:31:04+02:00",
                    "updated_at": "2026-08-27T11:31:04+02:00",
                    "cost": 80,
                    "barcode": "123456789012",
                    "taxable": true
                }
            ],
            "images": [
                {
                    "id": 1029,
                    "url": "https:\/\/cdn.joonweb.com\/images\/headphones-black.jpg",
                    "alt": "Black Wireless Headphones"
                }
            ],
            "image": {
                "id": 1029,
                "url": "https:\/\/cdn.joonweb.com\/images\/headphones-black.jpg",
                "alt": "Black Wireless Headphones"
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: Retrieve a list of products. Supports filtering by collection, vendor, etc.

##### Get product

**Method:** `GET`
**Path:** `/api/admin/26.0/products/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "product": {
        "id": 104593,
        "handle": "premium-wireless-headphones",
        "title": "Premium Wireless Headphones",
        "description": "<p>Experience true audio freedom with our premium wireless headphones.<\/p>",
        "label": "Sale",
        "body_html": "<p>Experience true audio freedom with our premium wireless headphones.<\/p>",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "published_at": "2026-08-27T11:31:04+02:00",
        "vendor": "AudioTech",
        "product_type": "Electronics",
        "product_category": "Headphones",
        "status": "public",
        "tags": "audio, wireless, new",
        "inventory_quantity": 150,
        "available": true,
        "available_for_sale": true,
        "track_quantity": 1,
        "variants": [
            {
                "id": 593821,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Black \/ Standard",
                "price": 149.990000000000009094947017729282379150390625,
                "compare_at_price": 199.990000000000009094947017729282379150390625,
                "sale_price": 149.990000000000009094947017729282379150390625,
                "discount": 50,
                "weight": 0.450000000000000011102230246251565404236316680908203125,
                "weight_unit": "kg",
                "sku": "ATH-BLK-01",
                "is_trackable": true,
                "track_quantity": true,
                "inventory_quantity": 100,
                "created_at": "2026-08-27T11:31:04+02:00",
                "updated_at": "2026-08-27T11:31:04+02:00",
                "cost": 80,
                "barcode": "123456789012",
                "taxable": true
            }
        ],
        "images": [
            {
                "id": 1029,
                "url": "https:\/\/cdn.joonweb.com\/images\/headphones-black.jpg",
                "alt": "Black Wireless Headphones"
            }
        ],
        "image": {
            "id": 1029,
            "url": "https:\/\/cdn.joonweb.com\/images\/headphones-black.jpg",
            "alt": "Black Wireless Headphones"
        }
    }
}
```

**Description**: Retrieve a single product by ID, including its variants and images.

##### Create product

**Method:** `POST`
**Path:** `/api/admin/26.0/products`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `title` | `string` | [Required] The title of the product |
| `body_html` | `string` | [Optional] HTML description of the product |
| `handle` | `string` | [Optional] Human-friendly unique string for the product URL |
| `vendor` | `string` | [Optional] The name of the vendor |
| `product_type` | `string` | [Optional] The product type |
| `status` | `string` | [Optional] Status of product: active, draft, or archived |
| `tags` | `string` | [Optional] Comma-separated tags |
| `options` | `array` | [Optional] Array of custom product options (e.g. Size, Color) |
| `options[].name` | `string` | [Required if options used] Name of the option (e.g. Size) |
| `options[].values` | `array` | [Required if options used] Array of string values (e.g. ['Small', 'Medium']) |
| `variants` | `array` | [Optional] Array of product variants |
| `variants[].price` | `float` | [Required if variants used] The price of the variant |
| `variants[].compare_at_price` | `float` | [Optional] The original price before sale |
| `variants[].cost_per_item` | `float` | [Optional] The cost of the variant to the merchant |
| `variants[].sku` | `string` | [Optional] Stock Keeping Unit |
| `variants[].barcode` | `string` | [Optional] Barcode, UPC, or ISBN |
| `variants[].weight` | `float` | [Optional] The weight of the variant |
| `variants[].weight_unit` | `string` | [Optional] Unit of measurement (g, kg, oz, lb) |
| `variants[].tracked` | `boolean` | [Optional] Whether inventory is tracked (1 or 0) |
| `variants[].position` | `integer` | [Optional] Sort order position |
| `variants[].image_id` | `integer` | [Optional] The ID of the image associated with this variant |
| `variants[].option1` | `string` | [Optional] Value for the first option (must match an option value) |
| `variants[].option2` | `string` | [Optional] Value for the second option |
| `variants[].option3` | `string` | [Optional] Value for the third option |
| `images` | `array` | [Optional] Array of product images |
| `images[].src` | `string` | [Required if images used] The source URL of the image |
| `images[].position` | `integer` | [Optional] Sort order position |
| `images[].variant_ids` | `array` | [Optional] Array of variant IDs to link this image to |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "product": {
        "title": "Premium Wireless Headphones",
        "body_html": "<p>Experience true audio freedom.<\/p>",
        "handle": "premium-wireless-headphones",
        "vendor": "AudioTech",
        "product_type": "Electronics",
        "status": "active",
        "tags": "audio, wireless, new",
        "options": [
            {
                "name": "Color",
                "values": [
                    "Black",
                    "White"
                ]
            }
        ],
        "variants": [
            {
                "price": 149.990000000000009094947017729282379150390625,
                "compare_at_price": 199.990000000000009094947017729282379150390625,
                "sku": "ATH-BLK-01",
                "weight": 0.450000000000000011102230246251565404236316680908203125,
                "weight_unit": "kg",
                "tracked": 1,
                "option1": "Black"
            },
            {
                "price": 149.990000000000009094947017729282379150390625,
                "compare_at_price": 199.990000000000009094947017729282379150390625,
                "sku": "ATH-WHT-01",
                "weight": 0.450000000000000011102230246251565404236316680908203125,
                "weight_unit": "kg",
                "tracked": 1,
                "option1": "White"
            }
        ],
        "images": [
            {
                "src": "https:\/\/example.com\/images\/headphones-black.jpg",
                "position": 1
            },
            {
                "src": "https:\/\/example.com\/images\/headphones-white.jpg",
                "position": 2
            }
        ]
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "product": {
        "id": 104593,
        "handle": "premium-wireless-headphones",
        "title": "Premium Wireless Headphones",
        "description": "<p>Experience true audio freedom with our premium wireless headphones.<\/p>",
        "label": "Sale",
        "body_html": "<p>Experience true audio freedom with our premium wireless headphones.<\/p>",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "published_at": "2026-08-27T11:31:04+02:00",
        "vendor": "AudioTech",
        "product_type": "Electronics",
        "product_category": "Headphones",
        "status": "public",
        "tags": "audio, wireless, new",
        "inventory_quantity": 150,
        "available": true,
        "available_for_sale": true,
        "track_quantity": 1,
        "variants": [
            {
                "id": 593821,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Black \/ Standard",
                "price": 149.990000000000009094947017729282379150390625,
                "compare_at_price": 199.990000000000009094947017729282379150390625,
                "sale_price": 149.990000000000009094947017729282379150390625,
                "discount": 50,
                "weight": 0.450000000000000011102230246251565404236316680908203125,
                "weight_unit": "kg",
                "sku": "ATH-BLK-01",
                "is_trackable": true,
                "track_quantity": true,
                "inventory_quantity": 100,
                "created_at": "2026-08-27T11:31:04+02:00",
                "updated_at": "2026-08-27T11:31:04+02:00",
                "cost": 80,
                "barcode": "123456789012",
                "taxable": true
            }
        ],
        "images": [
            {
                "id": 1029,
                "url": "https:\/\/cdn.joonweb.com\/images\/headphones-black.jpg",
                "alt": "Black Wireless Headphones"
            }
        ],
        "image": {
            "id": 1029,
            "url": "https:\/\/cdn.joonweb.com\/images\/headphones-black.jpg",
            "alt": "Black Wireless Headphones"
        }
    }
}
```

**Description**: Create a new product in the store.

##### Update product

**Method:** `PUT`
**Path:** `/api/admin/26.0/products/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `title` | `string` | [Required] The title of the product |
| `body_html` | `string` | [Optional] HTML description of the product |
| `handle` | `string` | [Optional] Human-friendly unique string for the product URL |
| `vendor` | `string` | [Optional] The name of the vendor |
| `product_type` | `string` | [Optional] The product type |
| `status` | `string` | [Optional] Status of product: active, draft, or archived |
| `tags` | `string` | [Optional] Comma-separated tags |
| `options` | `array` | [Optional] Array of custom product options (e.g. Size, Color) |
| `options[].name` | `string` | [Required if options used] Name of the option (e.g. Size) |
| `options[].values` | `array` | [Required if options used] Array of string values (e.g. ['Small', 'Medium']) |
| `variants` | `array` | [Optional] Array of product variants |
| `variants[].price` | `float` | [Required if variants used] The price of the variant |
| `variants[].compare_at_price` | `float` | [Optional] The original price before sale |
| `variants[].cost_per_item` | `float` | [Optional] The cost of the variant to the merchant |
| `variants[].sku` | `string` | [Optional] Stock Keeping Unit |
| `variants[].barcode` | `string` | [Optional] Barcode, UPC, or ISBN |
| `variants[].weight` | `float` | [Optional] The weight of the variant |
| `variants[].weight_unit` | `string` | [Optional] Unit of measurement (g, kg, oz, lb) |
| `variants[].tracked` | `boolean` | [Optional] Whether inventory is tracked (1 or 0) |
| `variants[].position` | `integer` | [Optional] Sort order position |
| `variants[].image_id` | `integer` | [Optional] The ID of the image associated with this variant |
| `variants[].option1` | `string` | [Optional] Value for the first option (must match an option value) |
| `variants[].option2` | `string` | [Optional] Value for the second option |
| `variants[].option3` | `string` | [Optional] Value for the third option |
| `images` | `array` | [Optional] Array of product images |
| `images[].src` | `string` | [Required if images used] The source URL of the image |
| `images[].position` | `integer` | [Optional] Sort order position |
| `images[].variant_ids` | `array` | [Optional] Array of variant IDs to link this image to |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "product": {
        "title": "Premium Wireless Headphones",
        "body_html": "<p>Experience true audio freedom.<\/p>",
        "handle": "premium-wireless-headphones",
        "vendor": "AudioTech",
        "product_type": "Electronics",
        "status": "active",
        "tags": "audio, wireless, new",
        "options": [
            {
                "name": "Color",
                "values": [
                    "Black",
                    "White"
                ]
            }
        ],
        "variants": [
            {
                "price": 149.990000000000009094947017729282379150390625,
                "compare_at_price": 199.990000000000009094947017729282379150390625,
                "sku": "ATH-BLK-01",
                "weight": 0.450000000000000011102230246251565404236316680908203125,
                "weight_unit": "kg",
                "tracked": 1,
                "option1": "Black"
            },
            {
                "price": 149.990000000000009094947017729282379150390625,
                "compare_at_price": 199.990000000000009094947017729282379150390625,
                "sku": "ATH-WHT-01",
                "weight": 0.450000000000000011102230246251565404236316680908203125,
                "weight_unit": "kg",
                "tracked": 1,
                "option1": "White"
            }
        ],
        "images": [
            {
                "src": "https:\/\/example.com\/images\/headphones-black.jpg",
                "position": 1
            },
            {
                "src": "https:\/\/example.com\/images\/headphones-white.jpg",
                "position": 2
            }
        ]
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "product": {
        "id": 104593,
        "handle": "premium-wireless-headphones",
        "title": "Premium Wireless Headphones",
        "description": "<p>Experience true audio freedom with our premium wireless headphones.<\/p>",
        "label": "Sale",
        "body_html": "<p>Experience true audio freedom with our premium wireless headphones.<\/p>",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "published_at": "2026-08-27T11:31:04+02:00",
        "vendor": "AudioTech",
        "product_type": "Electronics",
        "product_category": "Headphones",
        "status": "public",
        "tags": "audio, wireless, new",
        "inventory_quantity": 150,
        "available": true,
        "available_for_sale": true,
        "track_quantity": 1,
        "variants": [
            {
                "id": 593821,
                "variant_id": 4920,
                "product_id": 104593,
                "title": "Black \/ Standard",
                "price": 149.990000000000009094947017729282379150390625,
                "compare_at_price": 199.990000000000009094947017729282379150390625,
                "sale_price": 149.990000000000009094947017729282379150390625,
                "discount": 50,
                "weight": 0.450000000000000011102230246251565404236316680908203125,
                "weight_unit": "kg",
                "sku": "ATH-BLK-01",
                "is_trackable": true,
                "track_quantity": true,
                "inventory_quantity": 100,
                "created_at": "2026-08-27T11:31:04+02:00",
                "updated_at": "2026-08-27T11:31:04+02:00",
                "cost": 80,
                "barcode": "123456789012",
                "taxable": true
            }
        ],
        "images": [
            {
                "id": 1029,
                "url": "https:\/\/cdn.joonweb.com\/images\/headphones-black.jpg",
                "alt": "Black Wireless Headphones"
            }
        ],
        "image": {
            "id": 1029,
            "url": "https:\/\/cdn.joonweb.com\/images\/headphones-black.jpg",
            "alt": "Black Wireless Headphones"
        }
    }
}
```

**Description**: Update an existing product.

##### Delete product

**Method:** `DELETE`
**Path:** `/api/admin/26.0/products/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete a product permanently.

##### Count products

**Method:** `GET`
**Path:** `/api/admin/26.0/products/count`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |
| `collection_id` | `integer` | [Optional] Filter by collection ID |
| `vendor` | `string` | [Optional] Filter by vendor name |
| `product_type` | `string` | [Optional] Filter by product type |
| `available` | `boolean` | [Optional] Filter by availability (true/false) |
| `ids` | `string` | [Optional] Comma-separated list of product IDs |
| `handle` | `string` | [Optional] Filter by product handle |
| `min_stock` | `integer` | [Optional] Minimum inventory stock |
| `max_stock` | `integer` | [Optional] Maximum inventory stock |
| `search` | `string` | [Optional] Search in title or description |
| `inventory_status` | `string` | [Optional] Filter by status (available, out_of_stock) |
| `status` | `string` | [Optional] Filter by status (public, draft, private) |
| `min_price` | `float` | [Optional] Minimum price |
| `max_price` | `float` | [Optional] Maximum price |
| `fields` | `string` | [Optional] Comma-separated fields to return |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "count": 156
}
```

**Description**: Get a count of products matching specific criteria.

##### List product metafields

**Method:** `GET`
**Path:** `/api/admin/26.0/products/{id}/metafields`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafields": [
        {
            "id": 8492,
            "namespace": "global",
            "key": "title_tag",
            "value": "Buy Premium Headphones Online",
            "value_type": "string",
            "description": "SEO Title Tag",
            "owner_id": 104593,
            "owner_resource": "product",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List product metafields.

##### Create product metafield

**Method:** `POST`
**Path:** `/api/admin/26.0/products/{id}/metafields`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `namespace` | `string` | [Required] Grouping namespace |
| `key` | `string` | [Required] Metafield key |
| `value` | `string` | [Required] Metafield value |
| `value_type` | `string` | [Required] string, integer, json, etc. |
| `description` | `string` | [Optional] Description of the metafield |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafield": {
        "id": 8492,
        "namespace": "global",
        "key": "title_tag",
        "value": "Buy Premium Headphones Online",
        "value_type": "string",
        "description": "SEO Title Tag",
        "owner_id": 104593,
        "owner_resource": "product",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Create a product metafield.

##### Update product metafield

**Method:** `PUT`
**Path:** `/api/admin/26.0/products/{id}/metafields`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `namespace` | `string` | [Required] Grouping namespace |
| `key` | `string` | [Required] Metafield key |
| `value` | `string` | [Required] Metafield value |
| `value_type` | `string` | [Required] string, integer, json, etc. |
| `description` | `string` | [Optional] Description of the metafield |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafield": {
        "id": 8492,
        "namespace": "global",
        "key": "title_tag",
        "value": "Buy Premium Headphones Online",
        "value_type": "string",
        "description": "SEO Title Tag",
        "owner_id": 104593,
        "owner_resource": "product",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Update a product metafield.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### SEO Meta

#### SEO Meta Endpoints

##### Overview

### SEO Meta

Manage SEO metadata for various resources.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List SEO meta entries

**Method:** `GET`
**Path:** `/api/admin/26.0/sitemeta`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "sitemetas": [
        {
            "id": 500,
            "type": "product",
            "subtype": "104593",
            "title": "Premium Wireless Headphones - Joonweb Store",
            "description": "Buy Premium Wireless Headphones today and experience true freedom.",
            "keywords": "headphones, wireless, premium",
            "og_title": "Premium Wireless Headphones",
            "og_description": "Buy Premium Wireless Headphones today.",
            "og_image": "https:\/\/cdn.joonweb.com\/images\/headphones-og.jpg",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all SEO meta entries.

##### Create SEO meta

**Method:** `POST`
**Path:** `/api/admin/26.0/sitemeta`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `type` | `string` | [Required] Resource type (e.g. product, collection) |
| `subtype` | `string` | [Required] Resource ID or handle |
| `title` | `string` | [Optional] SEO title tag |
| `description` | `string` | [Optional] SEO meta description |
| `keywords` | `string` | [Optional] SEO meta keywords |
| `og_title` | `string` | [Optional] Open Graph title |
| `og_image` | `string` | [Optional] Open Graph image URL |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "type": "product",
    "subType": "",
    "data": "{\"title\": \"Meta Title\"}",
    "status": "active"
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "sitemeta": {
        "id": 500,
        "type": "product",
        "subtype": "104593",
        "title": "Premium Wireless Headphones - Joonweb Store",
        "description": "Buy Premium Wireless Headphones today and experience true freedom.",
        "keywords": "headphones, wireless, premium",
        "og_title": "Premium Wireless Headphones",
        "og_description": "Buy Premium Wireless Headphones today.",
        "og_image": "https:\/\/cdn.joonweb.com\/images\/headphones-og.jpg",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    },
    "message": "Updated successfully"
}
```

**Description**: Create a new SEO meta entry.

##### Get SEO meta by ID

**Method:** `GET`
**Path:** `/api/admin/26.0/sitemeta/id/{id:\d+}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "sitemetas": [
        {
            "id": 500,
            "type": "product",
            "subtype": "104593",
            "title": "Premium Wireless Headphones - Joonweb Store",
            "description": "Buy Premium Wireless Headphones today and experience true freedom.",
            "keywords": "headphones, wireless, premium",
            "og_title": "Premium Wireless Headphones",
            "og_description": "Buy Premium Wireless Headphones today.",
            "og_image": "https:\/\/cdn.joonweb.com\/images\/headphones-og.jpg",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: Retrieve SEO meta by ID.

##### Update SEO meta by ID

**Method:** `PUT`
**Path:** `/api/admin/26.0/sitemeta/id/{id:\d+}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `type` | `string` | [Required] Resource type (e.g. product, collection) |
| `subtype` | `string` | [Required] Resource ID or handle |
| `title` | `string` | [Optional] SEO title tag |
| `description` | `string` | [Optional] SEO meta description |
| `keywords` | `string` | [Optional] SEO meta keywords |
| `og_title` | `string` | [Optional] Open Graph title |
| `og_image` | `string` | [Optional] Open Graph image URL |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "type": "product",
    "data": "{\"title\": \"Updated Title\"}",
    "status": "active"
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "sitemeta": {
        "id": 500,
        "type": "product",
        "subtype": "104593",
        "title": "Premium Wireless Headphones - Joonweb Store",
        "description": "Buy Premium Wireless Headphones today and experience true freedom.",
        "keywords": "headphones, wireless, premium",
        "og_title": "Premium Wireless Headphones",
        "og_description": "Buy Premium Wireless Headphones today.",
        "og_image": "https:\/\/cdn.joonweb.com\/images\/headphones-og.jpg",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    },
    "message": "Updated successfully"
}
```

**Description**: Update SEO meta by ID.

##### Delete SEO meta by ID

**Method:** `DELETE`
**Path:** `/api/admin/26.0/sitemeta/id/{id:\d+}`

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete SEO meta by ID.

##### Get SEO meta by type

**Method:** `GET`
**Path:** `/api/admin/26.0/sitemeta/type/{type}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `type` | `string` | [Required] The resource type |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "sitemeta": {
        "id": 500,
        "type": "product",
        "subtype": "104593",
        "title": "Premium Wireless Headphones - Joonweb Store",
        "description": "Buy Premium Wireless Headphones today and experience true freedom.",
        "keywords": "headphones, wireless, premium",
        "og_title": "Premium Wireless Headphones",
        "og_description": "Buy Premium Wireless Headphones today.",
        "og_image": "https:\/\/cdn.joonweb.com\/images\/headphones-og.jpg",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Retrieve SEO meta by type.

##### Get SEO meta by type/subtype

**Method:** `GET`
**Path:** `/api/admin/26.0/sitemeta/type/{type}/{subtype}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `type` | `string` | [Required] The resource type |
| `subtype` | `string` | [Required] The resource subtype |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "sitemeta": {
        "id": 500,
        "type": "product",
        "subtype": "104593",
        "title": "Premium Wireless Headphones - Joonweb Store",
        "description": "Buy Premium Wireless Headphones today and experience true freedom.",
        "keywords": "headphones, wireless, premium",
        "og_title": "Premium Wireless Headphones",
        "og_description": "Buy Premium Wireless Headphones today.",
        "og_image": "https:\/\/cdn.joonweb.com\/images\/headphones-og.jpg",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Retrieve SEO meta by type/subtype.

##### Upsert SEO meta by type

**Method:** `PUT`
**Path:** `/api/admin/26.0/sitemeta/type/{type}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `type` | `string` | [Required] The resource type |
| `type` | `string` | [Required] Resource type (e.g. product, collection) |
| `subtype` | `string` | [Required] Resource ID or handle |
| `title` | `string` | [Optional] SEO title tag |
| `description` | `string` | [Optional] SEO meta description |
| `keywords` | `string` | [Optional] SEO meta keywords |
| `og_title` | `string` | [Optional] Open Graph title |
| `og_image` | `string` | [Optional] Open Graph image URL |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "data": "{\"title\": \"Upsert Title\"}",
    "status": "active"
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "sitemeta": {
        "id": 500,
        "type": "product",
        "subtype": "104593",
        "title": "Premium Wireless Headphones - Joonweb Store",
        "description": "Buy Premium Wireless Headphones today and experience true freedom.",
        "keywords": "headphones, wireless, premium",
        "og_title": "Premium Wireless Headphones",
        "og_description": "Buy Premium Wireless Headphones today.",
        "og_image": "https:\/\/cdn.joonweb.com\/images\/headphones-og.jpg",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    },
    "message": "Updated successfully"
}
```

**Description**: Upsert SEO meta by type.

##### Upsert SEO meta by type/subtype

**Method:** `PUT`
**Path:** `/api/admin/26.0/sitemeta/type/{type}/{subtype}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `type` | `string` | [Required] The resource type |
| `subtype` | `string` | [Required] The resource subtype |
| `type` | `string` | [Required] Resource type (e.g. product, collection) |
| `subtype` | `string` | [Required] Resource ID or handle |
| `title` | `string` | [Optional] SEO title tag |
| `description` | `string` | [Optional] SEO meta description |
| `keywords` | `string` | [Optional] SEO meta keywords |
| `og_title` | `string` | [Optional] Open Graph title |
| `og_image` | `string` | [Optional] Open Graph image URL |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "data": "{\"title\": \"Upsert Title\"}",
    "status": "active"
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "sitemeta": {
        "id": 500,
        "type": "product",
        "subtype": "104593",
        "title": "Premium Wireless Headphones - Joonweb Store",
        "description": "Buy Premium Wireless Headphones today and experience true freedom.",
        "keywords": "headphones, wireless, premium",
        "og_title": "Premium Wireless Headphones",
        "og_description": "Buy Premium Wireless Headphones today.",
        "og_image": "https:\/\/cdn.joonweb.com\/images\/headphones-og.jpg",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    },
    "message": "Updated successfully"
}
```

**Description**: Upsert SEO meta by type/subtype.

##### Delete SEO meta by type

**Method:** `DELETE`
**Path:** `/api/admin/26.0/sitemeta/type/{type}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `type` | `string` | [Required] The resource type |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete SEO meta by type.

##### Delete SEO meta by type/subtype

**Method:** `DELETE`
**Path:** `/api/admin/26.0/sitemeta/type/{type}/{subtype}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `type` | `string` | [Required] The resource type |
| `subtype` | `string` | [Required] The resource subtype |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete SEO meta by type/subtype.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Shipping Zones

#### Shipping Zones Endpoints

##### Overview

### Shipping Zones

Retrieve store shipping configurations.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List shipping zones

**Method:** `GET`
**Path:** `/api/admin/26.0/shipping_zones`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "shipping_zones": [
        {
            "id": 1,
            "name": "Domestic Shipping",
            "countries": [
                {
                    "id": 231,
                    "name": "United States",
                    "code": "US",
                    "tax": 0
                }
            ],
            "rates": [
                {
                    "id": 10,
                    "name": "Standard",
                    "price": 10,
                    "type": "flat",
                    "min_order_value": 0,
                    "max_order_value": 50
                },
                {
                    "id": 11,
                    "name": "Free Shipping",
                    "price": 0,
                    "type": "flat",
                    "min_order_value": 50,
                    "max_order_value": null
                }
            ]
        }
    ]
}
```

**Description**: List all shipping zones and rates.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Site Data

#### Site Data Endpoints

##### Overview

### Site Data

Endpoints for fetching site data and site-wide metafields.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### Get site data

**Method:** `GET`
**Path:** `/api/admin/26.0/site`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "site": [
        {
            "id": 104593,
            "title": "Example Site",
            "status": "active",
            "created_at": "2026-08-25T16:23:32Z",
            "updated_at": "2026-08-25T16:23:32Z"
        }
    ],
    "pagination": {
        "total": 156,
        "limit": 20,
        "page": 1
    }
}
```

**Description**: Retrieve basic configuration details for the current site.

##### List site metafields

**Method:** `GET`
**Path:** `/api/admin/26.0/site/metafields.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafields": [
        {
            "id": 8492,
            "namespace": "global",
            "key": "title_tag",
            "value": "Buy Premium Headphones Online",
            "value_type": "string",
            "description": "SEO Title Tag",
            "owner_id": 104593,
            "owner_resource": "product",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all metafields attached to the site object.

##### Create site metafield

**Method:** `POST`
**Path:** `/api/admin/26.0/site/metafields.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `namespace` | `string` | [Required] Grouping namespace |
| `key` | `string` | [Required] Metafield key |
| `value` | `string` | [Required] Metafield value |
| `value_type` | `string` | [Required] string, integer, json, etc. |
| `description` | `string` | [Optional] Description of the metafield |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "metafield": {
        "id": 8492,
        "namespace": "global",
        "key": "title_tag",
        "value": "Buy Premium Headphones Online",
        "value_type": "string",
        "description": "SEO Title Tag",
        "owner_id": 104593,
        "owner_resource": "product",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Create a site-wide metafield.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Themes

#### Themes Endpoints

##### Overview

### Themes

Manage theme configuration, code files, and assets.

All endpoints in this section require authentication using the `X-Joonweb-Access-Token` request header or an active App Bridge session.

##### List themes

**Method:** `GET`
**Path:** `/api/admin/26.0/themes`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "themes": [
        {
            "id": 102,
            "name": "Velocity Modern",
            "role": "main",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00",
            "previewable": true,
            "processing": false
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    },
    "access_level": "full"
}
```

**Description**: List all available themes installed on the site.

##### Get theme details

**Method:** `GET`
**Path:** `/api/admin/26.0/themes/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "theme": {
        "id": 102,
        "name": "Velocity Modern",
        "role": "main",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "previewable": true,
        "processing": false
    },
    "access_level": "full"
}
```

**Description**: Get details of a specific theme.

##### List theme files

**Method:** `GET`
**Path:** `/api/admin/26.0/themes/{id}/files`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "theme_name": "velocity-modern",
    "theme_details": {
        "id": 102,
        "name": "Velocity Modern",
        "role": "main",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "previewable": true,
        "processing": false
    },
    "files": [
        {
            "type": "folder",
            "name": "layout",
            "path": "\/layout",
            "children": [
                {
                    "type": "file",
                    "name": "theme.jw",
                    "path": "\/layout\/theme.jw"
                }
            ]
        }
    ]
}
```

**Description**: List all files within a theme architecture.

##### Get theme file

**Method:** `GET`
**Path:** `/api/admin/26.0/themes/{id}/files/file`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "file": {
        "name": "theme.jw",
        "path": "layout\/theme.jw",
        "type": "file",
        "extension": "jw",
        "last_modified": "2026-08-27T11:31:04+02:00",
        "created": "2026-08-27T11:31:04+02:00",
        "cdn": false,
        "content": "{% rules %}\n{\n  \"name\": \"Theme\",\n  \"schema\": []\n}\n{% endrules %}"
    },
    "theme": {
        "id": "{id}",
        "name": "Theme",
        "handle": "{id}"
    }
}
```

**Description**: Retrieve a specific theme file content.

##### Create/Update theme file

**Method:** `POST`
**Path:** `/api/admin/26.0/themes/{id}/files`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `key` | `string` | [Required] File path/key (e.g. layout/theme.jw) |
| `value` | `string` | [Required] File content to save |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "file": {
        "path": "example_path",
        "content": "example_content"
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "File created successfully"
}
```

##### Update Theme File

**Method:** `PUT`
**Path:** `/api/admin/26.0/themes/{id}/files/file`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |
| `key` | `string` | [Required] File path/key (e.g. layout/theme.jw) |
| `value` | `string` | [Required] File content to save |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
  "key": "layout/theme.jw",
  "value": "{% rules %}
..."
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "File updated successfully"
}
```

**Description**: Create or update a liquid, JS or CSS file in a theme.

##### Delete theme file

**Method:** `DELETE`
**Path:** `/api/admin/26.0/themes/{id}/files/file`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "File deleted successfully"
}
```

**Description**: Delete a theme file.

##### List theme assets

**Method:** `GET`
**Path:** `/api/admin/26.0/themes/{id}/assets`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "theme_name": "velocity-modern",
    "theme_details": {
        "id": 102,
        "name": "Velocity Modern",
        "role": "main",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00",
        "previewable": true,
        "processing": false
    },
    "assets": [
        {
            "type": "folder",
            "name": "layout",
            "path": "\/layout",
            "children": [
                {
                    "type": "file",
                    "name": "theme.jw",
                    "path": "\/layout\/theme.jw"
                }
            ]
        }
    ]
}
```

**Description**: List theme assets.

##### Get theme asset

**Method:** `GET`
**Path:** `/api/admin/26.0/themes/{id}/assets/file`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "file": {
        "name": "theme.jw",
        "path": "layout\/theme.jw",
        "type": "file",
        "extension": "jw",
        "last_modified": "2026-08-27T11:31:04+02:00",
        "created": "2026-08-27T11:31:04+02:00",
        "cdn": false,
        "content": "{% rules %}\n{\n  \"name\": \"Theme\",\n  \"schema\": []\n}\n{% endrules %}"
    },
    "theme": {
        "id": "{id}",
        "name": "Theme",
        "handle": "{id}"
    }
}
```

**Description**: Retrieve a specific asset file.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


### Webhooks

#### Webhooks Endpoints

##### Overview

# Webhooks Endpoints

Use the Webhooks API to programmatically create and manage webhook subscriptions for a site. 
If you want to learn more about the webhook architecture, how to verify webhook signatures, and see a full list of all available events you can subscribe to, please check out our comprehensive [Webhooks Guide](/docs/webhooks/webhook-events).

##### List webhook subscriptions

**Method:** `GET`
**Path:** `/api/admin/26.0/webhooks`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "webhooks": [
        {
            "id": 1029,
            "address": "https:\/\/yourapp.com\/webhooks\/orders-create",
            "topic": "orders\/create",
            "format": "json",
            "created_at": "2026-08-27T11:31:04+02:00",
            "updated_at": "2026-08-27T11:31:04+02:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}
```

**Description**: List all webhook subscriptions.

##### Create webhook

**Method:** `POST`
**Path:** `/api/admin/26.0/webhooks`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `topic` | `string` | [Required] Event topic (e.g. orders/create) |
| `address` | `string` | [Required] Endpoint URL to receive payload |
| `format` | `string` | [Optional] json or xml (default json) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "webhook": {
        "address": "example_address",
        "event": "example_event",
        "app_id": 104593,
        "secret": "example_secret"
    }
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "webhook": {
        "id": 1029,
        "address": "https:\/\/yourapp.com\/webhooks\/orders-create",
        "topic": "orders\/create",
        "format": "json",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Create a new webhook subscription.

##### Update webhook

**Method:** `PUT`
**Path:** `/api/admin/26.0/webhooks`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `topic` | `string` | [Required] Event topic (e.g. orders/create) |
| `address` | `string` | [Required] Endpoint URL to receive payload |
| `format` | `string` | [Optional] json or xml (default json) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Request Body
```json
{
    "webhook": []
}
```

###### Responses
**HTTP 200 OK**
```json
{
    "webhook": {
        "id": 1029,
        "address": "https:\/\/yourapp.com\/webhooks\/orders-create",
        "topic": "orders\/create",
        "format": "json",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Update an existing webhook subscription.

##### Get webhook

**Method:** `GET`
**Path:** `/api/admin/26.0/webhooks/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "webhook": {
        "id": 1029,
        "address": "https:\/\/yourapp.com\/webhooks\/orders-create",
        "topic": "orders\/create",
        "format": "json",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Retrieve a single webhook subscription.

##### Delete webhook

**Method:** `DELETE`
**Path:** `/api/admin/26.0/webhooks/{id}`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `id` | `integer/string` | [Required] The resource ID or handle |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "success": true,
    "message": "Deleted successfully"
}
```

**Description**: Delete a webhook subscription.

##### Trigger internal webhook

**Method:** `POST`
**Path:** `/api/admin/26.0/internal/webhooks/deliver`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `topic` | `string` | [Required] Event topic (e.g. orders/create) |
| `address` | `string` | [Required] Endpoint URL to receive payload |
| `format` | `string` | [Optional] json or xml (default json) |

###### Headers
| Header | Value |
|---|---|
| `X-Joonweb-Access-Token` | `jw_at_xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "webhook": {
        "id": 1029,
        "address": "https:\/\/yourapp.com\/webhooks\/orders-create",
        "topic": "orders\/create",
        "format": "json",
        "created_at": "2026-08-27T11:31:04+02:00",
        "updated_at": "2026-08-27T11:31:04+02:00"
    }
}
```

**Description**: Trigger an internal webhook delivery.

##### What's Next?

- 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks & scopes.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---

#### Webhook Events

##### Getting Started

# Webhook Events

A list of all available webhook events you can subscribe to. Use webhook subscriptions to receive real-time notifications about specific events happening on a site.

You can create app-specific or site-specific webhook subscriptions in JoonWeb using the REST API.
For each webhook subscription, you can define the `event` and the delivery endpoint (`address`) where notifications will be sent.
To create a new webhook subscription, send a POST request to the JoonWeb Webhooks API with parameters such as `event`, `address`, and `format`.
JoonWeb will then deliver real-time event data to your specified endpoint whenever the selected event occurs.

## Webhook Headers
When JoonWeb sends a webhook to your endpoint, the request includes the following headers for verification and context:
```http
Content-Type: application/json
X-Webhook-Signature: {hmac_signature}
X-JoonWeb-Site: example-store.myjoonweb.com
X-JoonWeb-Event: orders/create
X-JoonWeb-Event-Id: EV-123456-789
X-JoonWeb-API-Version: 26.0
```

## Verifying Webhooks
To verify that a webhook was genuinely sent by JoonWeb and hasn't been tampered with, calculate a SHA256 HMAC of the raw request payload using your **App Secret** (or Site Secret). Compare your computed hash with the `X-Webhook-Signature` header.

### PHP Verification Example
```php
<?php
// 1. Get the raw POST body
$payloadJson = file_get_contents('php://input');

// 2. Get the signature from headers
$headers = getallheaders();
$signature = $headers['X-Webhook-Signature'] ?? '';

// 3. Your App Secret
$app_secret = 'YOUR_APP_SECRET';

// 4. Calculate HMAC SHA256
$calculated_hmac = hash_hmac('sha256', $payloadJson, $app_secret);

// 5. Compare signatures safely
if (hash_equals($calculated_hmac, $signature)) {
    echo "Webhook verified!";
} else {
    http_response_code(401);
    echo "Webhook verification failed!";
}
?>
```

##### Webhook Events

###### Subscribed Events
| Event Topic | Description |
|---|---|
| `app_billings/update` |  |
| `app/uninstalled` |  |
| `app/scope_update` |  |
| `carts/create` |  |
| `carts/update` |  |
| `checkouts/create` |  |
| `checkouts/update` |  |
| `checkouts/delete` |  |
| `customers/create` |  |
| `customers/update` |  |
| `orders/create` |  |
| `orders/update` |  |
| `orders/cancelled` |  |
| `orders/paid` |  |
| `orders/partially_shipped` |  |
| `orders/shipped` |  |
| `shipping/create` |  |
| `shipping/update` |  |
| `shipping/cancelled` |  |
| `returns/approve` |  |
| `returns/request` |  |
| `returns/update` |  |
| `returns/complete` |  |

---

#### Access Scopes

##### Overview

Access scopes allow you to specify exactly what data your application can access. When you request an OAuth token, you must request the scopes required for your app to function.

Below is a categorized list of all available scopes.

### Analytics

| Scope | Description |
|-------|-------------|
| `read_analytics` | Read store analytics |

### Apps

| Scope | Description |
|-------|-------------|
| `read_apps` | Read Apps |

### Assigned Fulfillment Orders

| Scope | Description |
|-------|-------------|
| `write_assigned_fulfillment_orders` | Write and Update Assigned fulfillment orders |
| `read_assigned_fulfillment_orders` | Read-only Assigned fulfillment orders |

### Content

| Scope | Description |
|-------|-------------|
| `write_content` | Manage articles, blogs, comments, pages, and redirects |
| `read_content` | Manage articles, blogs, comments, pages, and redirects |

### Customers

| Scope | Description |
|-------|-------------|
| `write_customers` | Create and update Customers |
| `read_customers` | Read Customers |

### Discounts

| Scope | Description |
|-------|-------------|
| `write_discounts` | Create discount and coupons |
| `read_discounts` | View discount and coupons |

### Files

| Scope | Description |
|-------|-------------|
| `write_files` | Upload or create files |
| `read_files` | View files and media |

### Fulfillment

| Scope | Description |
|-------|-------------|
| `write_fulfillment` | Manage fulfillment |
| `read_fulfillment` | View fulfillments |

### Inventory

| Scope | Description |
|-------|-------------|
| `write_inventory` | Manage and update Inventory of Items |
| `read_inventory` | View Stocks and Inventory of Item |

### Locations

| Scope | Description |
|-------|-------------|
| `write_locations` | Create and Update warehouse locations |
| `read_locations` | View  warehouse locations |

### Manual Orders

| Scope | Description |
|-------|-------------|
| `write_manual_orders` | Create Manual Order |
| `read_manual_orders` | View Manual Order |

### Markets

| Scope | Description |
|-------|-------------|
| `write_markets` | Create, Update Store Market |
| `read_markets` | View Store Market Circle |

### Navigations

| Scope | Description |
|-------|-------------|
| `write_navigations` | Manage website navigations |
| `read_navigations` | View website navigations |

### Orders

| Scope | Description |
|-------|-------------|
| `write_orders` | Insert, manage or create order |
| `read_orders` | View Orders |

### Policies

| Scope | Description |
|-------|-------------|
| `write_policies` | Enable and update Policies of your website |
| `read_policies` | view policies of your website |

### Products

| Scope | Description |
|-------|-------------|
| `write_products` | Create or update products |
| `read_products` | View Product in Details |

### Returns

| Scope | Description |
|-------|-------------|
| `write_returns` | Accept, create or manage returns |
| `read_returns` | view order returns |

### Scipt Tags

| Scope | Description |
|-------|-------------|
| `write_scipt_tags` | Insert, create, delete or update script tags |
| `read_scipt_tags` | View Script Tags |

### Shipping

| Scope | Description |
|-------|-------------|
| `write_shipping` | Manage shipping and shipping rules |
| `read_shipping` | View shipping and shipping rules |

### Theme Code

| Scope | Description |
|-------|-------------|
| `write_theme_code` | Manage codes of your theme |

### Themes

| Scope | Description |
|-------|-------------|
| `write_themes` | Manage theme templates and assets |
| `read_themes` | View theme templates and assets |



---


## Ajax API

### Overview

- No articles available.

### Cart API

#### Get Cart (GET /cart.json)

##### Fetch Active Cart Payload

**Method:** `GET`
**Path:** ``

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `Accept` | `application/json` |

---

#### Add to Cart (POST /cart.json)

##### Add Product Variant to Cart

**Method:** `POST`
**Path:** ``

###### Headers
| Header | Value |
|---|---|
| `Content-Type` | `application/json` |

---

#### Update Item Quantity (POST /cart.json)

##### Change Cart Item Quantity

**Method:** `POST`
**Path:** ``

###### Headers
| Header | Value |
|---|---|
| `Content-Type` | `application/json` |

---

#### Remove Item & Quick Checkout

##### Delete Item from Cart (POST /cart.json)

**Method:** `POST`
**Path:** ``

###### Headers
| Header | Value |
|---|---|
| `Content-Type` | `application/json` |

##### ⚡ Open Quick Checkout JS (window.initiateQuickCheckout)

To immediately trigger the checkout flow without needing an extra API endpoint:

```javascript
// Triggers immediate quick checkout redirect if cart has items
window.initiateQuickCheckout();
```

---


### Search API

#### Suggestions & Predictive Search

##### Retrieve Matching Suggestions (GET /suggestions.json)

**Method:** `GET`
**Path:** ``

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `Accept` | `application/json` |

---


### Recommendations API

#### Product Recommendations (GET /recommendations.json)

##### Retrieve Recommended Products

**Method:** `GET`
**Path:** ``

###### Parameters
| Field | Type | Description |
|---|---|---|
| `limit` | `integer` | [Optional] Number of results to return (default 20, max 10000) |
| `page` | `integer` | [Optional] Page number to fetch (default 1) |
| `sort_by` | `string` | [Optional] Field to sort by (e.g. created_at, title) |
| `sort_order` | `string` | [Optional] Sort direction: asc or desc |

###### Headers
| Header | Value |
|---|---|
| `Accept` | `application/json` |

---


### Section Rendering API

#### Section Rendering & Dynamic Reloading

##### Dynamic Section Reloading (`?sections=...`)

The Section Rendering API allows frontend scripts to request rendered HTML for specific `.jw` sections without reloading the complete layout wrapper.

### Fetch Section HTML Snippet:
```javascript
// Fetch section HTML for section ID 102
const response = await fetch('/?sections=102');
const data = await response.json();
const sectionHTML = data['102'];

// Update section container DOM
document.getElementById('jw-section-102').innerHTML = sectionHTML;
```

### Ajax Pagination & Infinite Scroll Example:
```javascript
async function loadNextPage(nextPageUrl, gridContainerId) {
    const response = await fetch(`${nextPageUrl}&sections=product-grid`);
    const data = await response.json();
    
    const tempDiv = document.createElement('div');
    tempDiv.innerHTML = data['product-grid'];
    
    // Append new product cards to active grid container
    const newItems = tempDiv.querySelectorAll('.product-card');
    const grid = document.getElementById(gridContainerId);
    newItems.forEach(item => grid.appendChild(item));
}
```

---


## JW Language

### Template Syntax & Logic

#### .jw Template Syntax & Control Flow

##### Introduction to the JW Template Engine

The **JW Template Language** is the native, high-performance templating engine powering JoonWeb storefronts, `.jw` theme sections, components, blocks, and app extensions.

JW templates blend standard HTML with programming logic, expressions, loops, and visual customizer rules. All `.jw` templates compile directly on high-speed servers with zero runtime framework overhead on the buyer's browser.

### Core Delimiters

| Delimiter | Purpose | Example |
|---|---|---|
| `{{ ... }}` | **Expression Output**: Evaluates expressions, variables, and filters to emit content into HTML. | `{{ product.title }}` |
| `{% ... %}` | **Control Flow Tag**: Executes logic structures such as conditionals, loops, assignments, and schema. | `{% if product.in_stock %}` |
| `{# ... #}` | **Template Comment**: Stripped completely during compilation; never visible in rendered page source. | `{# Internal notes #}` |

### Whitespace Trimming
JW supports whitespace trimming using hyphens inside delimiters:
- `{{- variable -}}`: Trims whitespace to the left and right of the output expression.
- `{%- tag -%}`: Trims whitespace around logic statements to ensure compact, clean HTML output.

##### 1. Variables & Data Types

JW templates support all standard data types:

- **Strings**: `'Standard text'` or `"Double quoted text"`
- **Numbers**: Integers (`42`), Decimals (`19.99`)
- **Booleans**: `true` or `false`
- **Null**: `null` (evaluates as falsy)
- **Arrays (Sequences)**: `['apple', 'banana', 'orange']`
- **Hashes (Objects / Key-Value Maps)**: `{'size': 24, 'color': '#0f172a'}`

### Variable Assignment (`{% set %}`)
Assign or compute local variables using `{% set %}`:

```jw
{% set currency_sign = site.currency | default('₹') %}
{% set is_discounted = product.price > product.sale_price %}
{% set discount_amount = product.price - product.sale_price %}
{% set card_classes = section.colors2 ? section.colors2 : 'background5' %}

{% set button_sizes = {
  "small": "btns-sm",
  "medium": "btns-md",
  "large": "btns-lg"
} %}
{% set btn_class = button_sizes[section.desktop.buttonSize] ?? 'btns-md' %}
```

##### 2. Conditional Branching ({% if %})

Execute conditional logic using `{% if %}`, `{% elseif %}`, `{% else %}`, and `{% endif %}`:

```jw
{% if product.in_stock and product.sale_price > 0 %}
  <button class="btn btn-primary" onclick="JWCart.add('redirect', '{{ product.default_varient }}', 1)">
    Add to Cart — {{ site.currency }}{{ product.sale_price }}
  </button>
{% elseif product.preorder %}
  <button class="btn btn-warning">Pre-order Now</button>
{% else %}
  <button class="btn btn-secondary" disabled>Sold Out</button>
{% endif %}
```

### Boolean & Logical Operators
- `and`: Logical AND (true if both conditions are truthy)
- `or`: Logical OR (true if either condition is truthy)
- `not`: Logical NOT (inverts boolean condition)
- `()`: Group conditions for explicit precedence: `{% if (has_discount or has_coupon) and in_stock %}`

### Comparison Operators
- `==`: Loose equality
- `!=`: Inequality
- `<` / `>`: Less than / Greater than
- `<=` / `>=`: Less than or equal / Greater than or equal
- `in`: Checks if a value exists within an array or string: `{% if 'featured' in product.tags %}`
- `starts with` / `ends with`: String prefix and suffix matching: `{% if product.url starts with '/collections' %}`

##### 3. Loops & Collection Iteration ({% for %})

Iterate over arrays, products, blocks, or dictionaries using `{% for %}`:

```jw
<div class="product-grid row g-4">
  {% for product in products %}
    <div class="col-md-4">
      <div class="product-card card p-3 {{ section.colors2 ? section.colors2 : 'background5' }}">
        <img src="{{ product.cover }}" alt="{{ product.title }}" class="img-fluid rounded">
        <h4 class="fontStyle4 mt-2">{{ product.title }}</h4>
        <span class="price fontStyle7 fw-bold">{{ site.currency }}{{ product.sale_price }}</span>
      </div>
    </div>
  {% else %}
    <div class="col-12 text-center py-5">
      <p class="fontStyle7 text-muted">No products available in this collection.</p>
    </div>
  {% endfor %}
</div>
```

### The `loop` Context Object
Inside any `{% for %}` block, the special `loop` object provides helpful metadata:

| Property | Description |
|---|---|
| `loop.index` | 1-based current iteration number (`1`, `2`, `3`...) |
| `loop.index0` | 0-based current iteration number (`0`, `1`, `2`...) |
| `loop.first` | Boolean `true` on the first iteration of the loop |
| `loop.last` | Boolean `true` on the final iteration of the loop |
| `loop.length` | Total item count in the collection |
| `loop.revindex` | Number of iterations from the end (countdown down to `1`) |
| `loop.parent` | Accesses the outer loop context when nesting loops |

##### 4. Multi-Branch Switch Statements ({% switch %})

When rendering dynamic blocks configured in the JoonWeb Site Builder, use `{% switch %}` to dispatch markup based on `block.type`:

```jw
{% for block in section.blocks %}
  <div class="block-wrapper" {{ jw_attributes(block) }}>
    {% switch block.type %}
      {% case "heading" %}
        <h2 class="fontStyle2">{{ block.settings.title }}</h2>

      {% case "image_banner" %}
        <img src="{{ block.settings.image | asset_url }}" class="img-fluid rounded">

      {% case "cta_button" %}
        <a href="{{ block.settings.url.url }}" class="btns btns-md background1">
          {{ block.settings.url.label | default('Learn More') }}
        </a>

      {% default %}
        {# Universal fallback rendering for Theme App Extensions and standard blocks #}
        {{ render_block(block) }}
    {% endswitch %}
  </div>
{% endfor %}
```

##### 5. Pagination ({% paginate %}) & Verbatim ({% raw %})

### Pagination Wrapper
Easily paginate product feeds or collection items using `{% paginate %}`:

```jw
{% paginate collection.products by 12 %}
  <div class="row g-4">
    {% for product in collection.products %}
      <div class="col-md-3">
        {# Render product item card #}
      </div>
    {% endfor %}
  </div>

  <div class="pagination-wrapper mt-5 text-center">
    {{ paginate | default_pagination }}
  </div>
{% endpaginate %}
```

### Verbatim Raw Blocks (`{% raw %}`)
If your page embeds client-side frontend libraries (such as Vue, Mustache, or Angular) that use double curly braces, wrap them inside `{% raw %}` to prevent the JW Engine from evaluating them:

```jw
{% raw %}
  <div v-for="item in dynamicCartItems">
    <span>{{ item.name }}</span>
  </div>
{% endraw %}
```

##### 6. Template Inclusions ({% include %}, {% import %})

Organize complex storefront templates into reusable snippets located in `components/` or `blocks/`:

```jw
{# Include a reusable component snippet #}
{% include 'components/pagination.jw' %}

{# Include with local variable scope #}
{% include 'components/product-list.jw' with { product: featured_item } %}

{# Import macro helper functions #}
{% import 'components/breadcrumbs.jw' as breadcrumbs %}
```

> 💡 **Path Rule**: Inclusions must point to paths inside `components/`, `blocks/`, or `sections/`. System directories like `trash/`, `cache/`, or `rules/` are restricted.

##### 7. Operators & Type Tests

### String Concatenation (`~`)
Always use the `~` (tilde) operator to concatenate strings in JW templates:

```jw
{% set full_title = store.name ~ " - " ~ page.title %}
{% set image_alt = product.title ~ " High Resolution" %}
```

### Ternary & Null Coalescing Operators
- **Ternary**: `{{ section.colors ? section.colors : 'background5' }}`
- **Null Coalescing (`??`)**: `{{ section.desktop.borderRadius ?? 12 }}`

### Type Tests (`is`)
Test variable states using the `is` keyword:
- `is defined` / `is not defined`: Checks if variable exists in scope
- `is empty`: Checks if string or array is empty
- `is null`: Checks if variable is strictly null
- `is even` / `is odd`: Tests numeric parity
- `is iterable`: Tests if variable can be traversed in a `{% for %}` loop

##### 8. Essential Section Attributes & CSS Space Invariant

### Essential Customizer Functions
- **`{{ jw_attributes(block) }}`**: Emits DOM attributes for click-to-edit selection and drag-and-drop ordering in the Site Builder. **Always attach to custom block wrappers.**
- **`{{ render_block(block) }}`**: Renders installed app extension blocks. **Always place in the `{% default %}` switch branch.**

### ⚠️ The `{ #` CSS Whitespace Rule
In scoped section styles, always place a whitespace or newline after `{` before `#{{ section.id }}`:

```css
/* ❌ ERROR - Causes "Unclosed comment" parse failure because {# starts comment: */
@media (max-width: 768px) {#{{ section.id }} { padding: 20px; }}

/* ✅ CORRECT - Space separates brace from hash selector: */
@media (max-width: 768px) { #{{ section.id }} { padding: 20px; } }
```

---

#### JW Filters & Functions Reference

##### Overview of the JW Filter Pipeline

In the **JW Template Language**, filters transform, reformat, sanitize, and manipulate data within output expressions using the pipe symbol (`|`).

Multiple filters can be chained sequentially from left to right:
```jw
{{ product.title | trim | upper }}
{{ product.description | striptags | slice(0, 150) }}...
```

Parameters are passed inside parentheses: `| date("M d, Y")`, `| default('Fallback')`, `| slice(0, 5)`.

##### 1. Array & Collection Filters

Powerful array operations for collections, products, tags, and block sets:

| Filter | Purpose | Example | Output |
|---|---|---|---|
| `length` | Returns element count of array or string character count | `{{ ['a', 'b', 'c'] \| length }}` | `3` |
| `first` | Returns first element of collection | `{{ product.tags \| first }}` | `'organic'` |
| `last` | Returns final element of collection | `{{ cart.items \| last }}` | `Item Object` |
| `sort` | Sorts array elements alphabetically or numerically | `{{ tags \| sort \| join(', ') }}` | `'a, b, c'` |
| `join(delimiter)` | Joins elements into a delimited string | `{{ product.tags \| join(', ') }}` | `'pure, kesar, organic'` |
| `shuffle` | Randomizes array order (e.g. for related product grids) | `{% for item in products \| shuffle %}` | Random order |
| `merge(arr)` | Concatenates two arrays into one | `{{ listA \| merge(listB) }}` | Merged array |
| `column(key)` | Extracts a specific property from an array of objects | `{{ cart.items \| column('title') }}` | Array of titles |
| `find(fn)` | Returns the first item satisfying an arrow expression | `{{ products \| find(p => p.price > 1000) }}` | Matching Product |
| `map(fn)` | Projects each array item using an arrow expression | `{{ users \| map(u => "#{u.first} #{u.last}") }}` | Transformed array |
| `json_encode` | Encodes array or object into a JSON string | `{{ product.variants \| json_encode }}` | JSON string |

##### 2. String Transformation Filters

Format, trim, sanitize, and truncate text elements:

| Filter | Purpose | Example | Output |
|---|---|---|---|
| `split(sep)` | Splits string into array by delimiter | `{{ "a,b,c" \| split(',') }}` | `['a', 'b', 'c']` |
| `striptags` | Strips all HTML tags from rich text | `{{ blog.article \| striptags }}` | Clean plain text |
| `upper` | Converts text to uppercase | `{{ product.title \| upper }}` | `'SAFFRON'` |
| `lower` | Converts text to lowercase | `{{ category.name \| lower }}` | `'perfumes'` |
| `capitalize` | Capitalizes the first character | `{{ status \| capitalize }}` | `'Pending'` |
| `title` | Capitalizes every word (Title Case) | `{{ "pure organic honey" \| title }}` | `'Pure Organic Honey'` |
| `trim` | Strips surrounding whitespace | `{{ user_input \| trim }}` | Trimmed text |
| `escape` / `e` | Escapes HTML entities (`&`, `<`, `>`, `"`) | `{{ review.comment \| escape }}` | Safe HTML |
| `url_encode` | Percent-encodes text for query strings | `{{ "Kashmiri Saffron" \| url_encode }}` | `'Kashmiri+Saffron'` |
| `slice(start, len)` | Extracts substring or array slice | `{{ "JoonWeb Dev" \| slice(0, 7) }}` | `'JoonWeb'` |
| `nl2br` | Inserts `<br>` before all newlines | `{{ address \| nl2br }}` | Multi-line HTML |
| `charLimit(max)` | Truncates text to max length with ellipsis | `{{ product.description \| charLimit(60) }}` | Truncated copy |

##### 3. Number & Mathematical Filters

Perform rounding, integer conversion, and numerical formatting:

| Filter | Purpose | Example | Output |
|---|---|---|---|
| `round(precision)` | Rounds to nearest integer or specified decimal places | `{{ 4.67 \| round(1) }}` | `4.7` |
| `ceil` | Rounds number up to the next integer | `{{ 4.2 \| ceil }}` | `5` |
| `int` | Casts string or float to integer | `{{ "128" \| int }}` | `128` |
| `abs` | Computes the absolute numeric value | `{{ -450 \| abs }}` | `450` |
| `number_format(dec)` | Formats number with thousands separator | `{{ 1250000 \| number_format(2) }}` | `'1,250,000.00'` |

##### 4. Date & Time Formatting Filters

Transform timestamps and dates using standard date pattern tokens:

```jw
{# Full readable date #}
{{ blog.created | date("M d, Y") }}        {# Output: Oct 12, 2026 #}

{# Standard numeric date #}
{{ order.created_at | date("m/d/Y") }}     {# Output: 10/12/2026 #}

{# Time of day #}
{{ message.time | date("H:i:s") }}         {# Output: 14:30:00 #}

{# Current year for dynamic footer copyright #}
{{ "now" | date("Y") }}                    {# Output: 2026 #}
```

##### 5. Color Engine Filters

JoonWeb includes a built-in color manipulation engine for generating theme color variations on the fly:

| Filter | Description | Example |
|---|---|---|
| `color_to_hex` | Converts color string to standard hex code (`#0f172a`) | `{{ section.settings.accent \| color_to_hex }}` |
| `color_to_hsl` | Converts color to `hsl(h, s%, l%)` format | `{{ bg_color \| color_to_hsl }}` |
| `color_to_rgb` | Converts color to `rgb(r, g, b)` format | `{{ text_color \| color_to_rgb }}` |
| `color_to_oklch` | Converts color to modern perceptual `oklch(...)` space | `{{ brand_color \| color_to_oklch }}` |
| `color_darken(pct)` | Darkens color by specified percentage | `{{ button_color \| color_darken(10) }}` |
| `color_lighten(pct)` | Lightens color by specified percentage | `{{ button_color \| color_lighten(15) }}` |
| `color_saturate(pct)` | Increases color saturation | `{{ brand_color \| color_saturate(20) }}` |
| `color_brightness` | Returns luminance percentage (useful for contrast calculation) | `{{ bg \| color_brightness }}` |
| `color_mix(col, pct)` | Mixes two colors together by percentage | `{{ color1 \| color_mix(color2, 50) }}` |
| `color_modify(prop, val)` | Dynamically modifies color alpha or lightness | `{{ color1 \| color_modify('alpha', 0.8) }}` |

##### 6. HTML & CDN Asset URL Filters

Convert theme filenames into high-speed CDN URLs and generate HTML inclusion tags:

```jw
{# CDN Asset URL Filter #}
<img src="{{ 'hero-banner.jpg' | asset_url }}" alt="Hero">
<img src="{{ block.settings.icon | asset_url }}" alt="Icon">

{# Automatic HTML Link Tags #}
{{ 'style.css' | stylesheet_tag }}
{# Generates: <link rel="stylesheet" href="https://static.joonsite.com/assets/style.css"> #}

{{ 'slider.js' | script_tag }}
{# Generates: <script src="https://static.joonsite.com/assets/slider.js"></script> #}
```

##### 7. Fallback & Storefront Price Handling

### Fallback Filter (`default`)
Provides a fallback value when a variable is empty, undefined, or null:

```jw
<h1>{{ section.settings.title | default('Welcome to Our Store') }}</h1>
<div style="border-radius: {{ section.desktop.borderRadius | default(12) }}px;"></div>
```

### Storefront Currency & Price Formatting
In JoonWeb `.jw` templates, currency symbols and prices are rendered directly using the global `site.currency` variable alongside product price values (formatted with `number_format` as needed):

```jw
{# Standard currency output #}
<span class="price">{{ site.currency }}{{ product.sale_price }}</span>

{# With two decimal places using number_format #}
<span class="price">{{ site.currency }}{{ product.sale_price | number_format(2) }}</span>

{# Strikethrough compare-at price badge #}
{% if product.price > product.sale_price %}
  <span class="original-price text-muted text-decoration-line-through">
    {{ site.currency }}{{ product.price | number_format(2) }}
  </span>
  <span class="sale-price text-danger fw-bold ms-2">
    {{ site.currency }}{{ product.sale_price | number_format(2) }}
  </span>
{% endif %}
```

---

#### Global Context & Backend Object Schemas

##### Schema Type Activation & Section Data Binding

In the **JoonWeb Storefront Engine**, `.jw` sections are data-bound components. Declaring the `"type"` property in the root of your `{% rules %}` (or `{% schema %}`) configuration acts as a backend data pipeline trigger.

When the rendering engine executes a section, it evaluates the `"type"` and automatically hydrates the template scope with live e-commerce, editorial, or membership objects from the store database:

```json
{% rules %}
{
  "name": "Featured Products",
  "type": "ProductFeed",
  "settings": [
    { "type": "number", "id": "limit", "label": "Products to show", "default": 8 }
  ],
  "presets": [{ "name": "Featured Products", "category": "Products" }]
}
{% endrules %}
```

### Complete Schema `"type"` Activation Reference

| Schema `"type"` | Activated Objects | Scope & Data Injected |
|---|---|---|
| `"ProductFeed"` | `products` | Product feed array filtered by category, limit, and sort order |
| `"CollectionFeed"` | `collection.items` | Store collections listing with handles, banners, and product counts |
| `"catalogue"` | `catalogue.collections` | Hierarchical tabbed category matrix with nested product cards |
| `"cart"` | `cart` | Active customer cart session with line items, subtotal, and checkout trigger |
| `"BlogFeed"` | `blog.items`, `blog.category`, `blog.itemsCount` | Multi-post blog roll with excerpts, authors, categories, and views |
| `"blog"` / `"blog-post"` | `blog` | Editorial single-article detail scope with media, tags, and related posts |
| `"pricing"` / `"plans"` | `plans` | Membership subscription tiers with pricing, features, and buy triggers |
| `"siteform"` | `block.form` | Dynamic lead capture form with CSRF protection, signature, and CRM fields |
| *(None / Custom)* | `site`, `theme`, `section`, `user`, `query` | Global store context, typography system, customer session, and custom blocks |

##### Storefront Global Context Objects

Every `.jw` template, section, and component has access to global storefront context variables:

| Object | Description | Key Properties |
|---|---|---|
| `site` | Store merchant identity and configuration | `site.title`, `site.name`, `site.tagline`, `site.currency`, `site.currency_code`, `site.email`, `site.phone`, `site.address`, `site.social`, `site.url`, `site.id` |
| `theme` | Global design tokens from `theme_config.json` | `theme.colors.color1.value`, `theme.fontStyle.heading`, `theme.fontUnit` |
| `section` | Active section instance scope | `section.id`, `section.settings`, `section.blocks`, `section.order`, `section.blocks_order`, `section.colors` |
| `user` | Logged-in customer account data | `user.id`, `user.username`, `user.email`, `user.mobile`, `user.avatar`, `user.status`, `user.orders`, `user.orders_count`, `user.created` |
| `root` | Root URLs for internal storefront linking | `root.url` (store base path), `root.cdn` (media root) |
| `Property` | Section-level typography styling controls | `Property.title.style['size']`, `['family']`, `['weight']`, `['height']`, `['spacing']` |
| `query` | Associative array of HTTP GET query parameters | `{{ query.page }}`, `{{ query.sort_by }}`, `{{ query.q }}` |
| `current_url` | Full active URL string of the requested page | `https://store.example.com/collections/summer` |
| `isBuilder` | Boolean flag indicating if page is rendered inside visual editor | `{% if isBuilder %}` |
| `page` | Page metadata object | `page.title`, `page.handle`, `page.type` |

##### 1. Product Objects (`product` & `products`)

The `product` object is available on single product pages (`store-product`), while the `products` array is provided in product feed sections (`"type": "ProductFeed"`) and collection archives.

### Product Object Properties

| Property | Type | Description |
|---|---|---|
| `product.title` | `string` | Product name / headline |
| `product.url` | `string` | Relative product permalink (e.g. `./pure-saffron`) |
| `product.cover` | `string` | Primary CDN thumbnail URL |
| `product.cover_alt` | `string` | Image alternative text |
| `product.images` | `array` | Gallery images array (`value`, `alt`) |
| `product.description` | `string` | Full rich-text HTML description |
| `product.sku` | `string` | Default variant Stock Keeping Unit code |
| `product.sale_price` | `string` | Formatted selling price (e.g. `'2,499.00'`) |
| `product.sale_price_raw` | `float` | Raw numeric selling price (e.g. `2499.00`) |
| `product.price` | `string` | Formatted original MRP compare-at price |
| `product.price_raw` | `float` | Raw numeric MRP compare-at price |
| `product.discount` | `number` | Calculated savings percentage |
| `product.in_stock` | `boolean` | `1` if item is purchasable, `0` if out of stock |
| `product.stock` | `integer` | Available inventory quantity count |
| `product.ribbon` | `string` | Promotional badge label (e.g. `'Best Seller'`, `'Trending'`) |
| `product.default_varient` | `string` | Hash identifier of default variant (for `JWCart.add`) |
| `product.varients` | `string` | Selected variant title / summary |
| `product.options` | `array` | Variant option groups (e.g. Size, Color) |
| `product.variants` | `string` | JSON matrix of variant combinations |
| `product.combinations` | `array` | Array of combination objects with prices and hashes |
| `product.coupons` | `array` | Applicable discount coupons for this product |
| `product.rating` | `float` | Average customer review rating (e.g. `4.8`) |
| `product.reviews_count` | `integer` | Total number of published customer reviews |
| `product.extraprodesc` | `string` | Custom specification tabs content from product modules |
| `product.metafields` | `object` | Storefront custom metafield values |

### Product Card Template Example

```jw
{% for product in products %}
  <div class="col-md-3 mb-4">
    <div class="product-card card h-100 p-3 {{ section.colors2 | default('background5') }}">
      {% if product.ribbon %}
        <span class="badge bg-danger position-absolute top-0 start-0 m-2">{{ product.ribbon }}</span>
      {% endif %}
      
      <a href="{{ product.url }}" class="product-thumb d-block mb-3">
        <img src="{{ product.cover }}" alt="{{ product.cover_alt | default(product.title) }}" class="img-fluid rounded">
      </a>
      
      <h5 class="fontStyle5"><a href="{{ product.url }}" class="text-decoration-none">{{ product.title }}</a></h5>
      
      <div class="pricing d-flex gap-2 align-items-center mb-3">
        <span class="sale-price fontStyle7 fw-bold">{{ site.currency }}{{ product.sale_price }}</span>
        {% if product.price and product.price_raw > product.sale_price_raw %}
          <span class="compare-price fontStyle8 text-muted text-decoration-line-through">{{ site.currency }}{{ product.price }}</span>
        {% endif %}
      </div>

      {# 1-Click Add to Cart via JWCart JavaScript API #}
      {% if product.in_stock %}
        <button class="btns btns-sm background1 w-100" onclick="JWCart.add('redirect', '{{ product.default_varient }}', 1)">
          Add to Cart
        </button>
      {% else %}
        <button class="btns btns-sm btn-secondary w-100" disabled>Out of Stock</button>
      {% endif %}
    </div>
  </div>
{% endfor %}
```

##### 2. Shopping Cart Object (`cart`)

The `cart` object is available on all pages and cart drawer sections (`"type": "cart"`).

### Cart Object Properties

| Property | Type | Description |
|---|---|---|
| `cart.items` | `array` | List of items currently in the customer's cart |
| `cart.subtotal` | `string` | Formatted subtotal amount before discounts |
| `cart.discount` | `string` | Formatted savings amount |
| `cart.tax` | `string` | Calculated tax total |
| `cart.cod` | `string` | Shipping fee / COD charges |
| `cart.total` | `float` | Final payable checkout amount |
| `cart.checkout` | `string` | Pre-rendered attribute string (`data-checkout="..."`) |

### Line Item Properties (`cart.items`)

| Property | Type | Description |
|---|---|---|
| `item.hash` | `string` | Unique line item hash in cart session |
| `item.product_id` | `integer` | Underlying product numeric ID |
| `item.title` | `string` | Product title |
| `item.product_url` | `string` | Product page URL |
| `item.cover` | `string` | Variant / product thumbnail URL |
| `item['cover.alt']` | `string` | Image alternative text |
| `item.varients` | `string` | Selected variant attributes (e.g. `'Size: 1g'`) |
| `item.sale_price` | `float` | Unit price for this line item |
| `item.qty` | `integer` | Selected quantity count |
| `item.stock` | `integer` | Available warehouse inventory |
| `item.addons` | `array` | Custom product configuration attachments |

### Cart Drawer Template Example

```jw
{% if cart.items %}
  <div class="cart-items-wrapper">
    {% for item in cart.items %}
      <div class="cart-item d-flex align-items-center mb-3 pb-3 border-bottom">
        <img src="{{ item.cover }}" class="item-img rounded" width="60" alt="{{ item['cover.alt'] }}">
        <div class="item-details ms-3 flex-grow-1">
          <a href="{{ item.product_url }}" class="item-title fontStyle6 fw-bold text-decoration-none">{{ item.title }}</a>
          <div class="item-variants fontStyle8 text-muted">{{ item.varients }}</div>
          <div class="item-price fontStyle7 fw-bold mt-1">
            {{ site.currency }}{{ item.sale_price * item.qty }}
          </div>
        </div>

        {# Quantity Mutation Controls via JWCart.update #}
        <div class="quantity-controls d-flex align-items-center border rounded">
          <button class="btn btn-sm px-2 py-0" onclick="JWCart.update('redirect', '{{ item.hash }}', -1, 'negative', '{{ item.product_id }}')">-</button>
          <span class="px-2 fontStyle8">{{ item.qty }}</span>
          <button class="btn btn-sm px-2 py-0" onclick="JWCart.update('redirect', '{{ item.hash }}', 1, 'positive', '{{ item.product_id }}')">+</button>
        </div>
      </div>
    {% endfor %}
  </div>

  <div class="cart-summary mt-4 p-3 background2 rounded">
    <div class="d-flex justify-content-between mb-2"><span>Subtotal:</span><strong>{{ site.currency }}{{ cart.subtotal }}</strong></div>
    {% if cart.discount and cart.discount != '0.00' %}
      <div class="d-flex justify-content-between mb-2 text-success"><span>Savings:</span><strong>-{{ site.currency }}{{ cart.discount }}</strong></div>
    {% endif %}
    <div class="d-flex justify-content-between fontStyle4 mt-2 pt-2 border-top"><span>Total:</span><strong>{{ site.currency }}{{ cart.total }}</strong></div>
    
    {# 1-Click Hosted Checkout Initiation #}
    <a href="javascript:void(0);" id="jwCheckout__nav" class="btns btns-lg background1 w-100 text-center mt-3" {{ cart.checkout }}>
      Proceed to Checkout
    </a>
  </div>
{% else %}
  <div class="empty-cart text-center py-5">
    <p class="fontStyle6">Your shopping bag is empty.</p>
    <a href="{{ root.url }}/collections" class="btns btns-md background1">Explore Catalog</a>
  </div>
{% endif %}
```

##### 3. Collections & Catalogue Objects (`collection` & `catalogue`)

### Collection Feed (`"type": "CollectionFeed"`)
In collection listing sections, `collection.items` provides the list of merchant collections:

| Property | Type | Description |
|---|---|---|
| `item.title` | `string` | Collection title (e.g. `'Saffron & Spices'`) |
| `item.url` | `string` | Collection archive URL |
| `item.cover` / `item.image` | `string` | Collection banner or thumbnail URL |
| `item.description` | `string` | Collection descriptive synopsis |
| `item.count` | `integer` | Number of active products in this collection |

```jw
<div class="row">
  {% for col in collection.items %}
    <div class="col-md-4 mb-4">
      <a href="{{ col.url }}" class="collection-card d-block text-decoration-none">
        <img src="{{ col.cover }}" alt="{{ col.title }}" class="img-fluid rounded mb-2">
        <h4 class="fontStyle5 text-dark">{{ col.title }}</h4>
        <span class="text-muted fontStyle8">{{ col.count }} Products</span>
      </a>
    </div>
  {% endfor %}
</div>
```

### Tabbed Catalogue Matrix (`"type": "catalogue"`)
Sections with `"type": "catalogue"` inject `catalogue.collections` for multi-tab storefront navigation:

```jw
<ul class="nav nav-tabs">
  {% for key, col in catalogue.collections %}
    <li class="nav-item">
      <button class="nav-link {% if loop.first %}active{% endif %}" data-bs-toggle="tab" data-bs-target="#tab-{{ col.handle }}">
        {{ col.label }}
      </button>
    </li>
  {% endfor %}
</ul>

<div class="tab-content pt-4">
  {% for key, col in catalogue.collections %}
    <div class="tab-pane fade {% if loop.first %}show active{% endif %}" id="tab-{{ col.handle }}">
      <div class="row">
        {% for product in col.products %}
          <div class="col-md-3 mb-3">
            <a href="{{ product.url }}" class="text-decoration-none">
              <img src="{{ product.cover }}" class="img-fluid rounded mb-2">
              <h6>{{ product.title }}</h6>
              <strong>{{ site.currency }}{{ product.sale_price }}</strong>
            </a>
          </div>
        {% endfor %}
      </div>
    </div>
  {% endfor %}
</div>
```

##### 4. Editorial Blog Objects (`blog`: Feed vs Single Post)

The `blog` object operates in two modes depending on section `"type"`:

### Mode A: Multi-Post Feed (`"type": "BlogFeed"`)
In blog listing and recent news sections, `blog.items` contains an array of article previews:

| Property | Type | Description |
|---|---|---|
| `post.title` | `string` | Article headline |
| `post.url` | `string` | Full permalink to article |
| `post.img` | `string` | Cover image URL |
| `post['img.alt']` | `string` | Image alternative text |
| `post.summary` | `string` | Short synopsis |
| `post.description` | `string` | 320-character plain text excerpt |
| `post.article` | `string` | Full article body HTML |
| `post.category` | `string` | Category URL slug |
| `post.categoryName` | `string` | Category display title |
| `post.created` | `string` | Formatted date (e.g. `'12 Oct 2026'`) |
| `post.author` | `string` | Author name |
| `post.views` | `integer` | Total view counter |
| `post.is_featured` | `boolean` | `true` if marked as featured article |

### Mode B: Single Article Detail (`"type": "blog"` / `"blog-post"`)
On individual blog post pages, `blog` represents the active article:

| Property | Type | Description |
|---|---|---|
| `blog.title` | `string` | Article title |
| `blog.url` | `string` | Canonical article URL |
| `blog.media` | `string` | Main hero image URL |
| `blog['media.alt']` | `string` | Image alt text |
| `blog.summary` | `string` | Lead summary text |
| `blog.article` | `string` | Complete rich-text editorial content |
| `blog.author` | `string` | Author name |
| `blog.created` | `string` | Formatted publication date |
| `blog.readtime` | `integer` | Estimated reading duration in minutes |
| `blog.views` | `integer` | View count |
| `blog.share` | `string` | Pre-rendered social share icon links |
| `blog.tags` | `array` | Article tags (`title`, `url`) |
| `blog.related_post` | `array` | Related articles list |
| `blog.popular_post` | `array` | Trending articles list |

```jw
<article class="blog-details py-5">
  <h1 class="fontStyle1">{{ blog.title }}</h1>
  <div class="meta text-muted mb-4 fontStyle8">
    <span>By {{ blog.author }}</span> &bull; 
    <span>{{ blog.created }}</span> &bull; 
    <span>{{ blog.readtime }} min read</span>
  </div>

  {% if blog.media %}
    <img src="{{ blog.media }}" alt="{{ blog['media.alt'] }}" class="img-fluid rounded mb-4">
  {% endif %}

  <div class="article-content fontStyle7 leading-relaxed">
    {{ blog.article }}
  </div>

  {% if blog.tags %}
    <div class="tags mt-4">
      {% for tag in blog.tags %}
        <a href="{{ tag.url }}" class="badge bg-light text-dark me-1 text-decoration-none">#{{ tag.title }}</a>
      {% endfor %}
    </div>
  {% endif %}
</article>
```

##### 5. Pricing & Subscription Plans (`plans`)

When a section declares `"type": "pricing"` or `"type": "plans"`, the engine injects the `plans` array:

### Plan Object Properties

| Property | Type | Description |
|---|---|---|
| `plan.title` | `string` | Tier name (e.g. `'Starter'`, `'Professional'`) |
| `plan.tagline` | `string` | Plan subtitle description |
| `plan.price` | `float` | Recurring or one-time price float (e.g. `49.00`) |
| `plan.icon` | `string` | Tier badge or icon URL |
| `plan.features` | `array` | Feature list (`title`, `starred`, `info`) |
| `plan.ribbon` | `string` | Highlight ribbon (e.g. `'Most Popular'`) |
| `plan.highlight` | `string` | CSS class `'see-highlight-card'` if recommended |
| `plan.buynow` | `string` | Pre-rendered instant checkout form trigger |

```jw
<div class="row">
  {% for plan in plans %}
    <div class="col-md-4 mb-4">
      <div class="plan-card card p-4 h-100 {{ plan.highlight }}">
        {% if plan.ribbon %}
          <span class="badge bg-primary mb-2 align-self-start">{{ plan.ribbon }}</span>
        {% endif %}
        <h3>{{ plan.title }}</h3>
        <p class="text-muted">{{ plan.tagline }}</p>
        <div class="price fontStyle1 mb-4">{{ site.currency }}{{ plan.price }}</div>
        
        <ul class="features list-unstyled flex-grow-1">
          {% for feature in plan.features %}
            <li class="mb-2 {% if feature.starred %}fw-bold text-primary{% endif %}">
              <i class="fa fa-check me-2 text-success"></i>{{ feature.title }}
            </li>
          {% endfor %}
        </ul>

        {{ plan.buynow }}
      </div>
    </div>
  {% endfor %}
</div>
```

##### 6. Customer Account & Members Area (`user`)

Whenever a customer is authenticated on the store (`{% if user %}`), the `user` object is available across all storefront templates:

### User Object Properties

| Property | Type | Description |
|---|---|---|
| `user.id` | `integer` | Customer unique ID |
| `user.username` | `string` | Customer display username |
| `user.email` | `string` | Customer registered email address |
| `user.mobile` | `string` | Phone number |
| `user.avatar` | `string` | Profile avatar URL |
| `user.status` | `string` | Account status (`'active'`, `'pending'`) |
| `user.orders` | `array` | List of past customer purchase orders |
| `user.orders_count` | `integer` | Total count of placed orders |
| `user.created` | `string` | Member registration date |

```jw
{% if user %}
  <div class="user-greeting d-flex align-items-center">
    {% if user.avatar %}<img src="{{ user.avatar }}" class="rounded-circle me-2" width="32">{% endif %}
    <span>Welcome back, <strong>{{ user.username }}</strong> ({{ user.orders_count }} orders)</span>
    <a href="{{ root.url }}/account" class="btn btn-sm btn-outline-primary ms-3">My Account</a>
  </div>
{% else %}
  <div class="auth-links">
    <a href="{{ root.url }}/login" class="btn btn-sm btn-outline-secondary">Sign In</a>
    <a href="{{ root.url }}/register" class="btn btn-sm btn-primary ms-2">Register</a>
  </div>
{% endif %}
```

##### 7. Dynamic Forms (`siteform`) & Navigation (`section.navigation`)

### Dynamic Lead Forms (`type: "siteform"`)
JoonWeb form blocks manage CSRF tokens, anti-spam signatures, and CRM field persistence:

```jw
{% for block in section.blocks %}
  {% if block.type == "siteform" and block.form %}
    <form class="jw_dynamic_form p-4 background2 rounded" name="form_v_{{ block.form.id }}">
      <input type="hidden" name="csrf_token" value="{{ block.form.csrf }}">
      <signature style="display:none">{{ block.form.signature }}</signature>
      <input type="hidden" class="_tx_" value="{{ block.form.id }}">

      {% for field in block.form.fields %}
        <div class="mb-3">
          <label class="form-label fontStyle8 fw-bold">{{ field.label }}</label>
          {% if field.type == "textarea" %}
            <textarea name="{{ field.name }}" class="form-control fontStyle7" placeholder="{{ field.placeholder }}" {% if field.required == "yes" %}required{% endif %}></textarea>
          {% else %}
            <input type="{{ field.type }}" name="{{ field.name }}" class="form-control fontStyle7" placeholder="{{ field.placeholder }}" {% if field.required == "yes" %}required{% endif %}>
          {% endif %}
        </div>
      {% endfor %}

      <button type="submit" class="btns btns-md background1 w-100">
        {{ block.form.submit_label | default('Submit') }}
      </button>
    </form>
  {% endif %}
{% endfor %}
```

### Multi-Level Navigation Architecture (`section.navigation`)
Header and footer navigation menus support multi-level child trees:

```jw
<nav class="navbar-nav">
  {% for menu in section.navigation %}
    {% if menu.children %}
      {# Level 1 Dropdown #}
      <li class="nav-item dropdown">
        <a class="nav-link dropdown-toggle" href="{{ menu.link }}">{{ menu.label }}</a>
        <ul class="dropdown-menu">
          {% for submenu in menu.children %}
            <li>
              <a class="dropdown-item" href="{{ submenu.link }}">
                {% if submenu.icon %}<img src="{{ submenu.icon }}" width="16" class="me-1">{% endif %}
                {{ submenu.label }}
              </a>
            </li>
          {% endfor %}
        </ul>
      </li>
    {% else %}
      <li class="nav-item">
        <a class="nav-link" href="{{ menu.link }}" target="{{ menu.target }}">{{ menu.label }}</a>
      </li>
    {% endif %}
  {% endfor %}
</nav>
```

---


### Input Types & Rules Schema

#### JSON Rules Schema & Setting Types

##### Overview of {% rules %} Schema

The `{% rules %}` block placed at the bottom of any `.jw` file defines the settings UI rendered in the JoonWeb Site Builder sidebar, as well as the backend data-binding engine for that section.

### Schema Blueprint & Key Properties

```jw
{% rules %}
{
  "name": "Featured Products Grid",
  "type": "ProductFeed",
  "tag": "section",
  "class": "featured-products-section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Section Heading",
      "default": "Trending Products"
    },
    {
      "type": "number",
      "id": "limit",
      "label": "Number of Products",
      "default": 8
    },
    {
      "type": "range",
      "id": "padding_top",
      "label": "Top Spacing",
      "min": 0,
      "max": 100,
      "step": 5,
      "unit": "px",
      "default": 40
    }
  ],
  "blocks": [
    {
      "type": "badge",
      "name": "Offer Badge",
      "settings": [
        { "type": "text", "id": "badge_text", "label": "Text", "default": "Save 20%" }
      ]
    },
    { "type": "themes" },
    { "type": "apps" }
  ],
  "presets": [
    {
      "name": "Featured Products Grid",
      "category": "Products"
    }
  ]
}
{% endrules %}
```

### Root Configuration Keys

| Key | Type | Description |
|---|---|---|
| `name` | `string` | Human-readable section name displayed in the Site Builder |
| `type` | `string` | **Data Binding Trigger**: Binds backend objects (`"ProductFeed"`, `"CollectionFeed"`, `"catalogue"`, `"cart"`, `"BlogFeed"`, `"blog"`, `"pricing"`) |
| `tag` | `string` | Outer wrapping HTML element (`"section"`, `"header"`, `"footer"`, `"div"`) |
| `class` | `string` | Default CSS class names appended to the section wrapper |
| `settings` | `array` | Configurable input controls displayed in the customizer sidebar |
| `blocks` | `array` | Child components that can be added, sorted, or removed inside this section |
| `presets` | `array` | Default templates enabling the section to appear in the "Add Section" modal |

##### Complete Input Setting Types Reference

JoonWeb provides 16 specialized input setting types for theme customizers:

| Type | UI Control | Purpose & Example |
|---|---|---|
| `text` | Single-line text input | `{"type": "text", "id": "title", "label": "Heading", "default": "Title"}` |
| `quickEditor` | Inline text editor | `{"type": "quickEditor", "id": "heading", "label": "Heading"}` |
| `richtext` | Rich text WYSIWYG editor | `{"type": "richtext", "id": "body", "label": "Body Copy"}` |
| `textarea` | Multi-line text field | `{"type": "textarea", "id": "desc", "label": "Description"}` |
| `number` | Numeric stepper | `{"type": "number", "id": "limit", "label": "Count", "default": 8}` |
| `checkbox` | Boolean switch | `{"type": "checkbox", "id": "show_badge", "label": "Show Badge", "default": true}` |
| `select` | Dropdown menu | `{"type": "select", "id": "align", "label": "Alignment", "options": [{"label": "Left", "value": "left"}, {"label": "Center", "value": "center"}]}` |
| `radio` | Radio button group | `{"type": "radio", "id": "style", "label": "Card Style", "options": [...]}` |
| `color` | Hex color picker | `{"type": "color", "id": "accent", "label": "Accent Color", "default": "#2563eb"}` |
| `color_background` | Background picker | `{"type": "color_background", "id": "bg_color", "label": "Background"}` |
| `range` | Slider with step & unit | `{"type": "range", "id": "radius", "label": "Radius", "min": 0, "max": 40, "step": 2, "unit": "px", "default": 12}` |
| `image_picker` | Store media gallery picker | `{"type": "image_picker", "id": "cover", "label": "Cover Image"}` |
| `url` | Link picker object | `{"type": "url", "id": "button_link", "label": "Button Link", "default": {"url": "#", "label": "Shop Now", "target": "_self"}}` |
| `collection` | Store collections picker | `{"type": "collection", "id": "featured_col", "label": "Select Collection"}` |
| `product` | Product picker | `{"type": "product", "id": "featured_pro", "label": "Featured Product"}` |
| `socialicon` | Social profile links | `{"type": "socialicon", "id": "social", "label": "Social Channels"}` |
| `header` | Visual divider in sidebar | `{"type": "header", "content": "Typography & Spacing"}` |

---

#### Theme Blocks, Presets & Extensions Schema

##### Section Blocks Architecture

The `blocks` array inside `{% rules %}` defines child components that merchants can add, reorder, remove, and configure within a section.

```json
"blocks": [
  {
    "type": "testimonial_card",
    "name": "Customer Review",
    "settings": [
      { "type": "text", "id": "author", "label": "Customer Name", "default": "Sarah M." },
      { "type": "textarea", "id": "quote", "label": "Review Text" },
      { "type": "range", "id": "rating", "label": "Rating", "min": 1, "max": 5, "default": 5 }
    ]
  },
  { "type": "themes" },
  { "type": "apps" }
]
```

### Mandatory Interoperability Blocks
To maintain compatibility with third-party apps and the global block library:
1. `{"type": "themes"}`: Enables merchants to insert atomic theme blocks (like headings, dividers).
2. `{"type": "apps"}`: Enables Theme App Extensions from installed apps to inject app blocks into your section.

##### Presets & Site Builder Catalog

The `presets` array registers your section in the Site Builder "Add Section" dialog:

```json
"presets": [
  {
    "name": "Customer Testimonials",
    "category": "Social Proof",
    "settings": {
      "heading": "What Our Clients Say"
    },
    "blocks": [
      { "type": "testimonial_card", "settings": { "author": "John D.", "rating": 5 } },
      { "type": "testimonial_card", "settings": { "author": "Priya S.", "rating": 5 } }
    ]
  }
]
```

---


## JoonWeb CLI

### Overview & Setup

- No articles available.

### Command Reference

#### JoonWeb CLI Command Endpoints

##### 🚀 Overview of All CLI Commands

The **JoonWeb CLI** (`joonweb`) provides commands for scaffolding, running local servers, managing extensions, and deploying apps.

### Quick Command Index
| Command | Alias | Description |
| - | - | - |
| [`joonweb app init`](#section-119) | `create` | Initialize a new JoonWeb app |
| [`joonweb app serve`](#section-120) | `dev` | Start development server with auto-tunnel |
| [`joonweb refresh`](#section-121) | — | Reset background server and clear port locks |
| [`joonweb app regenerate`](#section-122) | `reset`, `reload` | Reload project templates from GitHub |
| [`joonweb app generate extension`](#section-123) | `ext` | Generate a new Theme App Extension |
| [`joonweb app deploy`](#section-124) | `push` | Deploy app release snapshot |
| [`joonweb login`](#section-125) | — | Authenticate with Partner Account |
| [`joonweb whoami`](#section-125) | — | Check active login status |
| [`joonweb logout`](#section-125) | — | Log out of Partner Account |
| [`joonweb update`](#section-125) | `upgrade` | Update CLI to latest version |
| [`joonweb uninstall`](#section-125) | `remove` | Uninstall CLI completely |

##### 1. `joonweb app init` (Create App)

Scaffolds a new JoonWeb app project from official templates.

```bash
joonweb app init
```

- **Alias**: `joonweb app create`
- **Interactive Options**:
  1. Authenticates your Partner account in the browser.
  2. Selects **Create a New JoonWeb App**.
  3. Chooses tech stack (Node+React, Express, PHP).
  4. Asks for **App Name**.
- **Output**: Generates project folder with [`joonweb.app.json`](/joonweb-cli/configuration/app-manifest).

##### 2. `joonweb app serve` (Development Server)

Starts your local development server with automatic HTTPS tunneling and hot reloading.

```bash
joonweb app serve [options]
```

- **Alias**: `joonweb app dev`  

### Available Options & Flags
| Flag | Description | Default |
| - | - | - |
| `--port <port>` | Specify local server port number | `11014` |
| `--no-tunnel` | Disable automatic HTTPS tunnel creation | `false` |
| `--no-open` | Disable browser auto-opening for OAuth consent | `false` |

### Usage Examples
```bash
# Default serve command
joonweb app serve

# Custom port without auto browser open
joonweb app serve --port 8080 --no-open
```

##### 3. `joonweb refresh` (Port Conflict Fix)

Resets the background development server and clears locked ports.

```bash
joonweb refresh
```

> 💡 **Troubleshooting**: If you encounter `ERR: already port open`, run `joonweb refresh` to terminate leftover background processes and clear port `11014` locks.

##### 4. `joonweb app regenerate` (Reload Templates)

Reloads all project template files from GitHub while preserving your `joonweb.app.json` config.

```bash
joonweb app regenerate
```

- **Aliases**: `joonweb app reset`, `joonweb app reload`  
- **Use Case**: Updates core SDK files to the latest version without overwriting your custom logic or manifest.

##### 5. `joonweb app generate extension` (App Extensions)

Generates a new app extension directory.

```bash
joonweb app generate extension
```

- **Alias**: `joonweb app generate ext`  
- **Output**: Generates `extensions/my-extension` with `blocks/`, `components/`, `assets/`, and `joonweb.extension.json`.

##### 6. `joonweb app deploy` (Release Version)

Deploys an app version snapshot to the JoonWeb platform.

```bash
joonweb app deploy [options]
```

- **Alias**: `joonweb app push`  

### Available Options & Flags
| Flag | Description | Default |
| - | - | - |
| `--env <env>` | Target deployment environment | `default` |
| `--no-release` | Skip creating a new live release version | `false` |

##### 7. Account & Maintenance Commands

### `joonweb login` 
Authenticates the CLI with your Partner account.
```bash
joonweb login [--shop <domain>]
```

### `joonweb whoami` 
Displays your active Partner login status.
```bash
joonweb whoami
```

### `joonweb logout` 
Logs out and clears cached session credentials.
```bash
joonweb logout
```

### `joonweb update` (Alias: `joonweb upgrade`)
Updates the CLI to the latest version.
```bash
joonweb update
```

### `joonweb uninstall` (Alias: `joonweb remove`)
Uninstalls the CLI completely.
```bash
joonweb uninstall
```

##### What's Next?

- ⚙️ **[App Manifest Reference (joonweb.app.json)](/joonweb-cli/configuration/app-manifest)** — Explore all JSON properties.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full step-by-step app development tutorial.
- 🎨 **[Create Theme App Extensions](/apps/theme-app-extensions/create-theme-app-extensions)** — Build storefront UI blocks.

---


### App Configuration

#### App Manifest (joonweb.app.json)

##### Overview

The `joonweb.app.json` file is the central manifest for your JoonWeb application. It contains your app ID, OAuth credentials, access scopes, proxy settings, webhooks, and framework template metadata.

> ⚠️ **CRITICAL WARNING**: `joonweb.app.json` is automatically generated by [`joonweb app init`](/joonweb-cli/commands/command-reference#joonweb-app-init). **It must NOT be deleted or manually replaced at any cost**, as it links your local project to your JoonWeb Technology Partner account.

##### Official joonweb.app.json Schema

Below is the complete official JSON structure of `joonweb.app.json`:

```json
{
  "appId": "8c21b0e81773747658577",
  "name": "mytestapp",
  "client_id": "0b990a0bb51fb125",
  "client_secret": "b90984d32211c49f8b94a3e04eb588f3be42",
  "app_url": "https://mytestapp.joonweb.app",
  "redirect_uri": "https://mytestapp.joonweb.app/auth/callback",
  "scopes": "read_products,write_products",
  "proxy": {
    "url": "https://mytestapp.joonweb.app/proxy",
    "status": "active"
  },
  "webhooks": [
    {
      "event": "products/create",
      "address": "https://mytestapp.joonweb.app/webhooks/products_create",
      "format": "json"
    }
  ],
  "template": "php",
  "embedded": true,
  "platform": "ecommerce",
  "version": "1.0.0"
}
```

##### Manifest Parameter Reference

| Property | Type | Description |
| - | - | - |
| `appId` | `string` | Unique application identifier registered on JoonWeb. |
| `name` | `string` | Name of your application. |
| `client_id` | `string` | Public OAuth Client ID used by App Bridge for iframe authentication. |
| `client_secret` | `string` | Private secret key used for server-side HMAC session verification and token exchange. |
| `app_url` | `string` | Main HTTPS application URL where your web server is hosted (updated automatically by `joonweb app serve`). |
| `redirect_uri` | `string` | OAuth authorization callback URL. |
| `scopes` | `string` | Comma-separated list of requested API permissions (e.g. `"read_products,write_products"`). |
| `proxy` | `object` | Storefront App Proxy configuration containing `url` and `status` (`"active"`). |
| `webhooks` | `array` | List of webhook event subscriptions containing `event`, `address`, and `format` (`"json"`). |
| `template` | `string` | Project framework template (e.g. `"php"`, `"node"`, `"react"`). |
| `embedded` | `boolean` | `true` if app runs embedded inside the JoonWeb Admin iframe. |
| `platform` | `string` | Target platform capability (`"ecommerce"`). |
| `version` | `string` | App version string (e.g. `"1.0.0"`). |

##### Proxy & Webhooks Configuration

### App Proxy (`proxy`)
An App Proxy routes requests from the merchant store domain (e.g. `store.myjoonweb.com/proxy`) to your application server.

```json
"proxy": {
  "url": "https://mytestapp.joonweb.app/proxy",
  "status": "active"
}
```

### Webhook Subscriptions (`webhooks`)
Webhooks notify your app when events happen in a merchant store.

```json
"webhooks": [
  {
    "event": "products/create",
    "address": "https://mytestapp.joonweb.app/webhooks/products_create",
    "format": "json"
  }
]
```

##### What's Next?

- 🚀 **[Run `joonweb app serve`](/joonweb-cli/commands/command-reference#joonweb-app-serve-development-server)** — Start dev server with tunnel.
- 🛠️ **[JoonWeb CLI Command Reference](/joonweb-cli/commands/command-reference)** — Explore all CLI commands.
- 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Full app creation tutorial.

---


## AI Agents

### Storefront Catalog

#### Storefront Catalog & AI Shopping Agents

##### Overview & Agentic Commerce Architecture

JoonWeb enables autonomous AI agents (such as **ChatGPT**, **Claude**, **Google Gemini**, **Perplexity**, and personal shopping assistants like **OpenClaw**) to directly discover products, verify inventory, check active payment methods, and initiate buyer checkout on any JoonWeb merchant store.

### How It Works

```
┌──────────────────────────────────────────────────────────────────┐
│                   AI Shopping Assistant / LLM                    │
│      (ChatGPT Actions / Claude Desktop MCP / Custom Agent)       │
└───────────────┬───────────────────────────────┬──────────────────┘
                │ 1. Discovery                  │ 2. Tool Calls
                ▼                               ▼
    ┌────────────────────────┐      ┌───────────────────────────┐
    │  /.well-known/ucp      │      │  /api/ucp/mcp             │
    │  (UCP Discovery 2026)  │      │  (Model Context Protocol) │
    └────────────────────────┘      └───────────┬───────────────┘
                                                │
                                    ┌───────────┴───────────┐
                                    ▼                       ▼
                         ┌─────────────────────┐ ┌─────────────────────┐
                         │   search_catalog    │ │ get_payment_methods │
                         │ get_product_details │ │ create_cart         │
                         │                     │ │ complete_checkout   │
                         └─────────────────────┘ └─────────────────────┘
```

### Core Standards Supported
- **Universal Commerce Protocol (UCP)**: Protocol version `2026-10-08`. Provides standard discovery at `/.well-known/ucp` and version profile `/.well-known/ucp/2026-10-08`.
- **Model Context Protocol (MCP)**: JSON-RPC 2.0 / SSE endpoint at `/api/ucp/mcp` giving AI tools direct access to search, products, payment methods, and checkout.
- **Tokenless Public Storefront Feed**: High-performance public feed at `/products.json` for bulk catalog indexing.
- **Dynamic Payment Gateway Engine**: Real-time evaluation of merchant active gateways (Razorpay, PhonePe, Cashfree, Paytm, Stripe, COD, Partial Payments) with postal PIN and order total rules.

##### UCP Discovery Endpoint

**Method:** `GET`
**Path:** `/.well-known/ucp`

###### Headers
| Header | Value |
|---|---|
| `Accept` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "ucp": {
        "version": "2026-10-08",
        "supported_versions": {
            "2026-10-08": "https://store.example.com/.well-known/ucp/2026-10-08",
            "2026-08-25": "https://store.example.com/.well-known/ucp/2026-08-25",
            "2026-04-08": "https://store.example.com/.well-known/ucp/2026-04-08",
            "2026-01-23": "https://store.example.com/.well-known/ucp/2026-01-23"
        },
        "services": {
            "dev.ucp.shopping": [
                {
                    "version": "2026-10-08",
                    "spec": "https://ucp.dev/2026-10-08/specification/overview/",
                    "transport": "mcp",
                    "endpoint": "https://store.example.com/api/ucp/mcp",
                    "schema": "https://ucp.dev/2026-10-08/services/shopping/mcp.openrpc.json"
                }
            ]
        },
        "capabilities": {
            "dev.joonweb.catalog": [
                {
                    "version": "2026-10-08",
                    "spec": "https://joonweb.dev/agents/catalog/store-catalog",
                    "schema": "https://joonweb.dev/ucp/schemas/2026-10-08/joonweb_catalog.json",
                    "extends": [
                        "dev.ucp.shopping.catalog.search",
                        "dev.ucp.shopping.catalog.lookup"
                    ],
                    "documentation_url": "https://joonweb.dev/agents/catalog/store-catalog"
                }
            ]
        },
        "payment_handlers": {
            "dev.joonweb.razorpay": [
                {
                    "id": "razorpay",
                    "version": "2026-10-08",
                    "spec": "https://razorpay.com/docs/payments/payment-gateway/",
                    "schema": "https://joonweb.dev/ucp/schemas/2026-10-08/razorpay.json",
                    "config": {
                        "enabled_payment_methods": [
                            "upi",
                            "card",
                            "netbanking",
                            "wallet"
                        ]
                    }
                }
            ],
            "dev.joonweb.cod": [
                {
                    "id": "cod",
                    "version": "2026-10-08",
                    "spec": "https://joonweb.dev/agents/catalog/store-catalog#active-payment-methods-api",
                    "schema": "https://joonweb.dev/ucp/schemas/2026-10-08/cod.json",
                    "config": {
                        "type": "cash_on_delivery"
                    }
                }
            ]
        }
    }
}
```

##### Storefront Products Feed

**Method:** `GET`
**Path:** `/products.json`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `page` | `integer` | [Optional] Page number to fetch (default: 1) |
| `limit` | `integer` | [Optional] Number of products to return (default: 30, max: 250) |
| `collection` | `string` | [Optional] Filter by collection slug or ID |
| `category` | `integer` | [Optional] Filter by category ID (ccid) |
| `q` | `string` | [Optional] Search keyword matching title or tags |

###### Headers
| Header | Value |
|---|---|
| `Accept` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "products": [
        {
            "id": 104593,
            "title": "Pure Kashmiri Mogra Saffron (Grade A1)",
            "handle": "pure-kashmiri-saffron",
            "body_html": "<p>Artisanal organic Grade A1 Kashmiri Saffron harvested from organic farms.</p>",
            "vendor": "Kasturika",
            "product_type": "Ayurveda & Wellness",
            "tags": [
                "saffron",
                "organic",
                "kesar",
                "wellness",
                "pure"
            ],
            "inventory_quantity": 45,
            "variants": [
                {
                    "id": 593821,
                    "variant_id": 4920,
                    "title": "1g / Premium Glass Jar",
                    "price": 999,
                    "compare_at_price": 1299,
                    "sale_price": 999,
                    "sku": "KAS-KESAR-1G",
                    "available": true,
                    "inventory_quantity": 45
                }
            ],
            "images": [
                {
                    "id": 1029,
                    "src": "https://static.joonsite.com/storage/104/media/saffron-1.jpg",
                    "alt": "Pure Kashmiri Mogra Saffron Jar"
                }
            ]
        }
    ],
    "pagination": {
        "total": 128,
        "limit": 30,
        "page": 1,
        "has_next": true
    }
}
```

##### Active Payment Methods Discovery

**Method:** `GET`
**Path:** `/api/ucp/mcp?tool=get_payment_methods`

###### Parameters
| Field | Type | Description |
|---|---|---|
| `postal_pin` | `string` | [Optional] Buyer PIN code to evaluate Cash on Delivery serviceability |
| `cart_total` | `number` | [Optional] Total order amount to evaluate COD limits and partial payment advance rules |

###### Headers
| Header | Value |
|---|---|
| `Accept` | `application/json` |

###### Responses
**HTTP 200 OK**
```json
{
    "site_id": 104,
    "store": "Kasturika",
    "currency": "INR",
    "has_online": true,
    "has_cod": true,
    "has_upi": true,
    "total_methods": 2,
    "methods": [
        {
            "code": "razorpay",
            "name": "Razorpay Secure Gateway",
            "type": "automatic",
            "is_online": true,
            "description": "UPI (Google Pay, PhonePe, Paytm), Cards & NetBanking",
            "supported_channels": [
                "upi",
                "card",
                "netbanking",
                "wallet"
            ],
            "available": true
        },
        {
            "code": "cod",
            "name": "Cash on Delivery",
            "type": "manual",
            "is_online": false,
            "description": "Pay cash upon delivery at your doorstep",
            "supported_channels": [
                "cash"
            ],
            "available": true,
            "cod_rate": 0
        }
    ]
}
```

##### Model Context Protocol (MCP) Tools Reference

The JoonWeb MCP Server exposes 5 standardized tools under `/api/ucp/mcp`:

### 1. `search_catalog`
Searches the store catalog using keyword matching, collection filters, price ranges, and inventory status.
- **Parameters**: `query` (string), `category` (string), `min_price` (number), `max_price` (number), `in_stock_only` (boolean), `limit` (integer).
- **Returns**: Array of matching products with variants, images, and live pricing.

### 2. `get_product_details`
Retrieves comprehensive details for a specific product including variant combinations, addon options, and high-resolution media gallery.
- **Parameters**: `product_id` (integer) or `handle` (string).
- **Returns**: Detailed product record with full pricing combinations (`price` vs `sale_price`), specifications, and SKU availability.

### 3. `get_payment_methods`
Discovers all payment gateways actively configured and enabled by the merchant, validating postal code serviceability and order total limits.
- **Parameters**: `postal_pin` (string, optional), `cart_total` (number, optional).
- **Returns**: Available online gateways (Razorpay, PhonePe, Stripe, Cashfree, Paytm), Cash on Delivery status, and partial advance payment rules.

### 4. `create_cart`
Adds items to the buyer's storefront shopping cart session with selected variant combo IDs and addon options.
- **Parameters**: `items` (array of `{variant_id, quantity, addons}`).
- **Returns**: Cart summary, line items, subtotal, and tax breakdowns.

### 5. `complete_checkout`
Generates a pre-filled, instant checkout permalink that the AI agent provides to the buyer for one-click payment approval.
- **Parameters**: `cart_token` (string), `payment_method` (string), `customer_info` (object with name, email, phone, address).
- **Returns**: Instant hosted checkout URL and order preview permalink.

##### MCP Client Configuration (Claude Desktop / Cursor)

```json
{
  "mcpServers": {
    "joonweb-store": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "https://store.example.com/api/ucp/mcp"
      ]
    }
  }
}
```

##### ChatGPT Custom GPT Action OpenAPI 3.1 Specification

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "JoonWeb Storefront Autonomous Commerce API",
    "version": "2026-10-08",
    "description": "Enables ChatGPT to search products, inspect inventory, verify active payment gateways, and generate instant checkout permalinks."
  },
  "servers": [
    {
      "url": "https://store.example.com"
    }
  ],
  "paths": {
    "/products.json": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search products in the catalog",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search keyword" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": { "description": "Product catalog feed" }
        }
      }
    },
    "/api/ucp/mcp": {
      "get": {
        "operationId": "getPaymentMethods",
        "summary": "Discover active store payment methods",
        "parameters": [
          { "name": "tool", "in": "query", "schema": { "type": "string", "default": "get_payment_methods" } },
          { "name": "postal_pin", "in": "query", "schema": { "type": "string" } },
          { "name": "cart_total", "in": "query", "schema": { "type": "number" } }
        ],
        "responses": {
          "200": { "description": "List of active payment methods" }
        }
      }
    }
  }
}
```

##### Autonomous Agent Shopping Flow (Python Example)

```python
import requests

STORE_URL = "https://store.example.com"

# 1. Discover UCP Capabilities
discovery_res = requests.get(f"{STORE_URL}/.well-known/ucp").json()
print("Discovered UCP Version:", discovery_res["ucp"]["version"])

# 2. Search Store Catalog for Products
search_res = requests.get(f"{STORE_URL}/products.json", params={"q": "perfume", "limit": 5}).json()
products = search_res.get("products", [])
print(f"Found {len(products)} matching products.")

if products:
    target_product = products[0]
    first_variant = target_product["variants"][0]
    print(f"Selected: {target_product['title']} - Variant #{first_variant['variant_id']}")
    print(f"Price: ₹{first_variant['sale_price']} (MRP: ₹{first_variant['price']})")

    # 3. Check Active Payment Gateways
    payments_res = requests.get(
        f"{STORE_URL}/api/ucp/mcp",
        params={"tool": "get_payment_methods", "cart_total": first_variant["sale_price"]}
    ).json()
    enabled_methods = [m["name"] for m in payments_res.get("methods", []) if m["available"]]
    print("Available Payment Methods:", ", ".join(enabled_methods))

    # 4. Generate 1-Click Hosted Checkout Permalink
    checkout_url = f"{STORE_URL}/checkout?variant_id={first_variant['variant_id']}&quantity=1"
    print("Buyer Checkout Permalink:", checkout_url)
```

##### What's Next?

- 📐 **[JoonWeb Catalog Schema (2026-10-08)](https://joonweb.dev/ucp/schemas/2026-10-08/joonweb_catalog.json)** — Complete JSON Schema Draft 2020-12 definition.
- 🔑 **[Admin REST API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and authentication.
- 🛒 **[Ajax Cart API Reference](/ajax-api/cart-api/get-cart)** — Front-end cart mutation and section rendering.
- 🛠️ **[JoonWeb CLI Guide](/joonweb-cli/overview/overview)** — Build and test apps from the command line.

---


### Theme & Section Skills

#### Build JoonWeb (.JW) Section with ChatGPT

##### Overview & 1-Click Launch with ChatGPT

JoonWeb enables developers, merchants, and theme creators to rapidly generate production-ready `.jw` sections using OpenAI's **ChatGPT** (GPT-4o, ChatGPT Plus, and Custom GPTs).

By pairing ChatGPT with the official **`jw-theme-sections`** skill, you can generate responsive storefront sections with Bootstrap 5.3 utilities, scoped styles, and fully populated JSON rules schemas in seconds.

---

### 🚀 1-Click Execution

Click below to immediately open ChatGPT with the official JoonWeb skill and prompt pre-loaded:

[**⚡ Launch Directly in ChatGPT**](https://chatgpt.com/?hints=search&q=You%20are%20an%20Expert%20JoonWeb%20Theme%20Developer.%20Follow%20the%20official%20JoonWeb%20section%20specifications%20at%20https%3A%2F%2Fjoonweb.dev%2Fskills%2Fjw-theme-sections%2FSKILL.md%20to%20build%20a%20production-ready%20.jw%20section.)

> **Skill File Reference:** [https://joonweb.dev/skills/jw-theme-sections/SKILL.md](https://joonweb.dev/skills/jw-theme-sections/SKILL.md)

##### ChatGPT Prompt Template & Workflow

### JW Language Conditionals & Truthiness
| Legacy Syntax | JW Language Equivalent (Native) |
|---|---|
| `{% if title != blank %}` | `{% if title is not empty %}` or `{% if title != '' %}` |
| `{% if title != nil %}` | `{% if title is not null %}` |
| `{% if title != "" %}` | `{% if title != '' %}` |
| `{% if title != blank and title != nil %}` | `{% if title is defined and title is not empty %}` |
| `{% if title == blank %}` | `{% if title is empty %}` or `{% if title == '' %}` |
| `{% if title == nil %}` | `{% if title is null %}` |

### Master Prompt for ChatGPT

Copy and paste the following prompt into ChatGPT to generate any custom section:

```markdown
You are an Expert JoonWeb Theme Developer. Follow the official specifications:
https://joonweb.dev/skills/jw-theme-sections/SKILL.md

Create a production-ready, ultra-premium [SECTION_NAME] section in .jw format for an [Online Store / Informative Website].

Strict Requirements:
1. Top Comment: {# Copy and paste this code directly into the JoonWeb Theme Editor (.jw file) #}
2. File Order (Mandatory): Variables {% set %} -> <style> (Scoped CSS MUST come BEFORE <section>) -> <section> (Outer HTML container) -> <script> -> {# Do not change if you don't know #} -> {% rules %}.
3. Outer Wrapper: <section id="jw-section-{{ section.id }}" class="xx background{{ sc }} ..." data-xx="1" data-bl="{{ site ? 0 : 1 }}" style="...">.
4. Conditionals: Use != '' (never != blank).
5. Styling: Bootstrap 5.3 + Bootstrap Icons + FontAwesome 6. Scoped CSS using {{ S }} with builder overrides {{ S }}[data-bl="1"].
6. Editable Blocks: <div class="xx-blk" data-jw-block> and {% switch block.type %} ... {% default %} {{ render_block(block) }} {% endswitch %}.
7. Valid Setting Types: ONLY radio (yes/no), quickEditor (<p>...</p>), text, url, image_picker, range, select, color, color_background, header, paragraph, buttons, socialicon. Never use checkbox or textarea.
8. Schema Blocks & Presets: Append {"type": "themes"} and {"type": "apps"} to schema blocks. NEVER include themes or apps in presets blocks.
9. Clean Comments: No unnecessary, bulky decorative comments.
```

### Custom GPT Setup (Optional)
If you are configuring a custom GPT for your development agency or team:
1. In the GPT **Instructions** field, paste the system prompt above.
2. Add `https://joonweb.dev/skills/jw-theme-sections/SKILL.md` to GPT Knowledge.
3. Your GPT is now primed to generate valid single-file `.jw` templates on demand.

##### Ready-to-Use Prompt Examples for ChatGPT

Here are tested prompt examples you can copy and send to ChatGPT right now:

#### 1. Full-Width Hero Banner
```text
Create a full-width Hero Banner section (.jw) for an informative agency website with:
- Background image picker with dark overlay opacity range slider (0% to 100%)
- Large responsive heading and lead paragraph
- Primary CTA button and secondary outline button with link pickers
- Text alignment selector (left, center, right)
- Scoped CSS under #jw-section-{{ section.id }}
- Valid JSON {% rules %} ... {% endrules %} with fully populated default presets
```

#### 2. E-Commerce Featured Product Grid with Instant Cart
```text
Generate an e-commerce Featured Product Grid section in .jw format with:
- Collection selector setting and product count slider (4 to 12)
- Responsive Bootstrap 5.3 grid with column controls (2, 3, or 4 columns)
- Product card featuring: hover zoom effect, discount percentage badge, sale price, MRP strikethrough, and stock badge
- Instant Ajax Add to Cart button using JWCart.add(variantId, 1, this)
- Scoped CSS under #jw-section-{{ section.id }}
- Valid JSON {% rules %} ... {% endrules %} with fully populated default presets
```

#### 3. Customer Testimonials Carousel
```text
Generate an interactive Customer Testimonials section in .jw format with:
- Section header with title and subtitle
- Repeatable blocks for individual testimonials
- Each block containing: 5-star rating display, customer quote text, avatar image picker, customer name, and role/company
- Responsive Bootstrap 5.3 card layout
- Scoped CSS for card hover lift and quotation styling
- Valid JSON {% rules %} ... {% endrules %} with fully populated default presets (3 demo testimonials)
```

##### Production .jw File Anatomy & Output

When generated correctly, your `.jw` section will follow this precise single-file structure:

```html
{# ======================================================== #}
{# JoonWeb Hero Banner Section (.jw)                        #}
{# ======================================================== #}
<section id="jw-section-{{ section.id }}" class="jw-hero-banner position-relative overflow-hidden" style="padding-top: {{ section.settings.padding_top }}px; padding-bottom: {{ section.settings.padding_bottom }}px;">
  <div class="container position-relative z-1 py-5">
    <div class="row align-items-center {% if section.settings.alignment == 'center' %}justify-content-center text-center{% else %}justify-content-start text-start{% endif %}">
      <div class="col-12 col-lg-8">
        {% if section.settings.heading %}
          <h1 class="display-4 fw-bold mb-3 text-white">{{ section.settings.heading }}</h1>
        {% endif %}
        {% if section.settings.subheading %}
          <p class="lead mb-4 text-white-50">{{ section.settings.subheading }}</p>
        {% endif %}
        {% if section.settings.btn_text and section.settings.btn_link %}
          <a href="{{ section.settings.btn_link }}" class="btn btn-primary btn-lg px-4">{{ section.settings.btn_text }}</a>
        {% endif %}
      </div>
    </div>
  </div>
</section>

<style>
#jw-section-{{ section.id }} {
  min-height: {{ section.settings.min_height | default(450) }}px;
}
</style>

{% rules %}
{
  "name": "Hero Banner",
  "settings": [
    { "type": "text", "id": "heading", "label": "Main Heading", "default": "Next-Gen Digital Commerce" },
    { "type": "textarea", "id": "subheading", "label": "Subheading", "default": "Elevate your storefront experience." },
    { "type": "text", "id": "btn_text", "label": "Button Label", "default": "Shop New Arrivals" },
    { "type": "url", "id": "btn_link", "label": "Button URL", "default": "/collections/all" }
  ],
  "presets": [
    {
      "name": "Hero Banner",
      "settings": {
        "heading": "Next-Gen Digital Commerce",
        "subheading": "Elevate your storefront experience.",
        "btn_text": "Shop New Arrivals",
        "btn_link": "/collections/all"
      }
    }
  ]
}
{% endrules %}
```

### Installation
Save the generated code as `sections/[section_name].jw` in your theme folder. It will instantly appear in the JoonWeb visual editor sidebar for merchants to add and customize!

---

#### Build JoonWeb Section with Claude

##### Overview & Claude Setup

Anthropic's **Claude 3.5 Sonnet** offers industry-leading reasoning for structural code generation, responsive Bootstrap 5.3 markup, and JSON schema formatting.

By linking Claude to the official **`jw-theme-sections`** skill, you can generate complete, error-free `.jw` templates that adhere strictly to JoonWeb's storefront architecture.

---

### Quick Launch (1-Click Pre-Loaded Prompt)
[**⚡ Launch in Claude with Pre-Loaded Prompt**](https://claude.ai/new?q=You%20are%20an%20Expert%20JoonWeb%20Theme%20Developer.%20Follow%20the%20official%20JoonWeb%20section%20specifications%20at%20https%3A%2F%2Fjoonweb.dev%2Fskills%2Fjw-theme-sections%2FSKILL.md%20to%20build%20a%20production-ready%20.jw%20section.)

Claude natively supports instant prompt pre-loading via URL parameter (`https://claude.ai/new?q=...`), allowing you to start generating sections in one click.

### Integrating the Skill into Claude Projects
1. Open [Claude.ai](https://claude.ai) and navigate to **Projects**.
2. Create or open your JoonWeb development project.
3. Under **Project Knowledge**, add a reference or paste the contents of:
   `https://joonweb.dev/skills/jw-theme-sections/SKILL.md`
4. Now, any section generation prompt in your project will automatically follow official JoonWeb guidelines.

##### Claude Prompt Template

Copy and paste this prompt directly into your Claude chat:

```markdown
Please review the official JoonWeb Theme Development Skill:
https://joonweb.dev/skills/jw-theme-sections/SKILL.md

Generate a complete, production-ready `.jw` section for: [SECTION_NAME].

Architecture Guidelines:
1. Top Comment: {# Copy and paste this code directly into the JoonWeb Theme Editor (.jw file) #}
2. File Order: Variables {% set %} -> <style> (Scoped CSS MUST come BEFORE <section>) -> <section> (Outer HTML container) -> <script> -> {# Do not change if you don't know #} -> {% rules %}.
3. Outer Wrapper: <section id="jw-section-{{ section.id }}" class="xx background{{ sc }} ..." data-xx="1" data-bl="{{ site ? 0 : 1 }}" style="...">.
4. Conditionals: Use != '' (never != blank). Loops use {% for %}.
5. Scoped CSS: Scope all rules under {{ S }} with builder overrides {{ S }}[data-bl="1"].
6. Editable Blocks: Use data-jw-block.
7. Schema & Presets: ONLY valid types (radio yes/no, quickEditor, text, image_picker, range). Append {"type": "themes"} and {"type": "apps"} to schema blocks. NEVER include themes or apps in presets.
8. E-Commerce Elements: Use ProductFeed, JWCart.add, cart, and site.currency where applicable.
9. Clean Comments: No unnecessary, bulky decorative comments.
```

##### Claude Example Prompts & Scenarios

#### 1. Interactive Product Grid with Live Ajax Drawer
```text
Generate a Featured Product Grid section (.jw) for an online jewelry store:
- Collection picker and 4 to 8 products slider
- Responsive 2 columns on mobile, 4 columns on desktop
- Product card showing featured image, title, sale price, MRP strikethrough, and discount badge
- Instant Ajax Add to Cart button triggering JWCart.add(variantId, 1, this)
- Scoped CSS for card hover lift and smooth transitions
- Populated default presets with 4 demo products
```

#### 2. Sticky Announcement Bar with Coupon Badge
```text
Generate a sticky top Announcement Bar section (.jw) with:
- Background and text color pickers
- Marquee ticker animation toggle
- Promotional text message with clickable link
- Coupon code badge with 1-click copy script
- Dismiss close button with session storage memory
- Scoped CSS for ticker marquee animation
- Populated default presets with free shipping promo
```

##### Key Technical Rules for Claude Outputs

When validating Claude's generated `.jw` code, verify the following standards:

1. **Pure JW Syntax**: Conditionals must use `{% if %}`, `{% elseif %}`, `{% else %}`, `{% endif %}`. Brackets around conditions `(x == y)` should be avoided.
2. **Bootstrap 5.3 Only**: Layout must rely entirely on Bootstrap 5.3 grid (`row`, `col-*`), utilities, and Bootstrap Icons (`bi bi-*`). Tailwind CSS is never used inside `.jw` storefront sections.
3. **Block Rendering**: Blocks must be rendered via:
   ```html
   {% switch block.type %}
     {% default %}
       {{ render_block(block) }}
   {% endswitch %}
   ```
4. **Populated Presets**: The `presets` array in `{% rules %}` must contain full default values and block configurations so the section works out-of-the-box.

---

#### Build JoonWeb Section with Cursor

##### Overview & 1-Click Installation in Cursor

**Cursor AI** allows you to scaffold, edit, and refactor `.jw` sections directly inside your local development workspace using inline chat and Composer.

To make Cursor understand JoonWeb architecture and activate the **`@jw-theme`** command, external developers must install the skill locally into their workspace.

---

### Step 1: 1-Click Skill Installation (Terminal)

Run this single command in the root folder of your theme repository:

```bash
mkdir -p .cursor/rules && curl -s https://joonweb.dev/skills/jw-theme-sections/SKILL.md > .cursor/rules/jw-theme.mdc
```

This immediately downloads the official 1,000+ line JoonWeb Theme Skill into `.cursor/rules/jw-theme.mdc`. Cursor v0.42+ will automatically index the file, enabling the **`@jw-theme`** symbol across Composer and Chat without needing to restart!

---

### Alternative Installation Methods

#### For AI Agents (Google Antigravity, Windsurf, Copilot Workspace):
```bash
mkdir -p .agents/skills/jw-theme-sections && curl -s https://joonweb.dev/skills/jw-theme-sections/SKILL.md > .agents/skills/jw-theme-sections/SKILL.md
```

#### For Legacy Universal `.cursorrules`:
```bash
curl -s https://joonweb.dev/skills/jw-theme-sections/SKILL.md > .cursorrules
```

##### Cursor In-Editor Commands & Composer Prompts

Once `.cursorrules` is set up, you can command Cursor directly in **Composer (Cmd+I / Ctrl+I)** or **Chat (Cmd+L / Ctrl+L)**:

#### Scaffold a New Section
```text
@jw-theme Generate a new sections/customer-reviews.jw section with 5-star ratings, avatar image picker, quote block, and responsive 3-column Bootstrap card layout with populated presets.
```

#### Add Ajax Add-to-Cart to Existing Cards
```text
@jw-theme Update the product card button in this .jw file to use JWCart.add(variantId, 1, this) with a loading spinner state on click.
```

#### Add Settings to Rules Schema
```text
@jw-theme Add background color picker, padding top/bottom range sliders (20px to 120px), and an alignment select dropdown to the {% rules %} schema.
```

#### Build Storefront Header with Live Search (/suggestions.json)
```text
@jw-theme Generate a sticky header.jw section with brand logo, nav links, cart count badge, and debounced predictive search calling /suggestions.json?q={query}&limit=8 displaying products, collections, and blog articles.
```

---


## Webhooks