> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront

> Display a product grid on any WordPress page.

# Khaime Storefront

Display a beautiful product grid on any WordPress page with the `[khaime_storefront]` shortcode.

<Card title="Download Plugin" icon="download" href="https://api.khaime.com/wordpress/download/khaime-storefront">
  khaime-storefront.zip
</Card>

<Note>
  As of v2.0.0 the storefront is server-rendered. Your **Merchant ID** is configured once in **Settings → Khaime** — you don't pass it on the shortcode. The JS SDK only loads when a shopper clicks **Proceed to checkout**.
</Note>

## Basic Usage

```
[khaime_storefront]
```

## Filter by Category

Show only products from a specific category. You can filter by category **ID** or by **slug/name** — whichever is more convenient.

**By ID** (numeric, from your Khaime dashboard):

```
[khaime_storefront category_id="5"]
```

**By slug** (URL-friendly, lowercase-with-dashes):

```
[khaime_storefront category_slug="online-courses"]
```

**By name** (case-insensitive, matches even if no slug is set):

```
[khaime_storefront category_slug="Online Courses"]
```

**Multiple categories** (comma-separated):

```
[khaime_storefront category_slug="online-courses,workshops"]
```

Combine with other filters to narrow results further:

```
[khaime_storefront category_slug="online-courses" type="digital" sort="newest"]
```

<Note>
  If `category_slug` matches no categories, the result is empty — the filter is **not** silently dropped. This guards against typos returning the full catalog.
</Note>

## Full Example

```
[khaime_storefront
    product_url="/product/{slug}"
    category_slug="online-courses"
    type="digital"
    sort="newest"
    product_ids="123,456,789"
    columns="3"
    limit="12"
    show_currency="true"
    show_pagination="true"
]
```

## Attributes

| Attribute         | Description                                                                                                   | Default                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `limit`           | Products per page (1–48)                                                                                      | `12`                             |
| `columns`         | Grid columns                                                                                                  | `4`                              |
| `category_id`     | Filter by product category ID                                                                                 | —                                |
| `category_slug`   | Filter by category slug or name (case-insensitive). Comma-separated for multiple. Unioned with `category_id`. | —                                |
| `product_ids`     | Filter to specific product IDs (comma-separated)                                                              | —                                |
| `category`        | Free-text category filter passed to the API                                                                   | —                                |
| `type`            | Filter by product type: `digital`, `live_event`, `physical`, etc.                                             | —                                |
| `sort`            | Sort: `price_asc`, `price_desc`, `newest`, `oldest`, `title_asc`, `title_desc`                                | —                                |
| `title`           | Inline heading rendered above the grid. Leave empty to avoid duplicating your WordPress page title.           | `""`                             |
| `show_currency`   | Show the inline currency switcher (only renders when more than one currency is enabled)                       | `true`                           |
| `show_pagination` | Show pagination controls below the grid                                                                       | `true`                           |
| `empty_message`   | Text shown when the result set is empty                                                                       | `No products found.`             |
| `product_url`     | URL pattern for product links. Use `{slug}` placeholder.                                                      | (from settings)                  |
| `store_url`       | "Continue shopping" target used by cart/empty states                                                          | (from settings)                  |
| `cart_url`        | Destination for the cart icon when `cart_display` is `page`                                                   | (from settings, default `/cart`) |
| `cart_display`    | `drawer` or `page` — see [Cart Page](/plugins/wordpress/cart)                                                 | `drawer`                         |

<Note>
  Legacy attributes from the v1 JS plugin (`theme`, `spacing`, `card_style`, `primary_color`, `sandbox`, `merchant_id`, `hover_effect`, etc.) are **accepted and silently ignored** so existing shortcodes don't error after the upgrade. They no longer have any effect — remove them when you next touch the page.
</Note>

## Admin Settings

Most setup happens once at **Settings → Khaime**:

| Setting                             | Purpose                                                                                                                                 |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Merchant ID**                     | Numeric ID from your Khaime dashboard (Settings → API). Required.                                                                       |
| **Environment**                     | `production` or `development`.                                                                                                          |
| **Product URL prefix**              | Slug used for auto-routed product pages (default `product`, so URLs look like `/product/{slug}`).                                       |
| **Store Page URL**                  | "Continue shopping" target for the cart and empty states.                                                                               |
| **Cart display**                    | Global default for `cart_display` — `drawer` or `page`.                                                                                 |
| **Cart Page URL**                   | Destination when `Cart display` is `page` (default `/cart`). Must point to a page containing `[khaime_cart]`.                           |
| **Enabled currencies**              | Which of your merchant's supported currencies appear in the switcher. The floating switcher auto-renders when more than one is enabled. |
| **Custom API URL / Custom SDK URL** | Override endpoints (development / staging only).                                                                                        |

## Cart Display

The storefront includes a floating cart icon. By default it opens a slide-out drawer. To send shoppers to a dedicated cart page instead, set `cart_display` to `page` (either globally in **Settings → Khaime → Cart display** or per-instance on the shortcode). See the [Cart Page](/plugins/wordpress/cart) guide for setup.

## Theming

The storefront adapts to your host theme by deriving surfaces, hairlines, and mutings from `currentColor`, so the embed stays legible on light or dark WordPress themes without configuration. There's no per-shortcode theme toggle — styling is inherited.

## CSS Customization

Override styles using the `ks-` prefix:

```css theme={null}
.ks-root { /* Main container */ }
.ks-grid { /* Product grid */ }
.ks-card { /* Product card */ }
.ks-card-title { /* Product title */ }
.ks-card-price { /* Product price */ }
```