> ## Documentation Index
> Fetch the complete documentation index at: https://codebeans-wishlyst.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer overview

> How Codebeans Wishlyst plugs into a Shopify theme, and the ways you can extend it.

Codebeans Wishlyst works with any Online Store 2.0 theme without code changes. When a theme does something unusual, or when you want full control over the markup, this section shows you how the pieces fit together and where you can hook in.

## How it is built

> [card] Theme app extension
>
> Two app embeds (**Wishlist Engine** and **Wishlist icon**) and two app blocks (**Add to Wishlist Button** and **Shopy Wishlist Page**). They load the storefront scripts and styles.

> [card] App proxy
>
> Every storefront request goes to `/apps/cbwishlist/*` on the shop's own domain. Shopify signs it and forwards it to the app.

> [card] Customer account extensions
>
> **Wishlist Account** and **Shared Wishlist Account** add wishlist pages to the new Shopify customer accounts.

> [card] Shop metafields
>
> Widget settings, feature toggles and custom templates are stored as app-owned shop metafields, so Liquid can read them on first paint.

## Ways to extend it

> [card] [Manual placement](https://codebeans-wishlyst.mintlify.site/developers/manual-placement.md)
>
> Put the button, collection hearts, wishlist page, nav menu and cart button exactly where you want them.

> [card] [JavaScript API & events](https://codebeans-wishlyst.mintlify.site/developers/javascript-api.md)
>
> Listen for wishlist changes, re-scan the page after AJAX updates, and debug placement.

> [card] [Custom page templates](https://codebeans-wishlyst.mintlify.site/developers/page-templates.md)
>
> Rewrite the wishlist page markup with EJS templates and your own CSS.

> [card] [REST API](https://codebeans-wishlyst.mintlify.site/api-reference/introduction.md)
>
> Build wishlists into a headless storefront or a mobile app.

> [card] [Shopify Flow](https://codebeans-wishlyst.mintlify.site/developers/shopify-flow.md)
>
> Start Flow workflows when a shopper adds an item to a wishlist.

> [card] [AI assistants (MCP)](https://codebeans-wishlyst.mintlify.site/developers/mcp-server.md)
>
> Let Claude and other MCP clients read your wishlist data.

## Storefront request flow

```mermaid theme={null}
sequenceDiagram
    participant B as Shopper's browser
    participant S as Shop domain (/apps/cbwishlist)
    participant A as Codebeans Wishlyst app
    B->>S: POST /apps/cbwishlist/wishlist
    S->>A: Signed proxy request (+ logged_in_customer_id)
    A-->>S: JSON response
    S-->>B: JSON response
```

The app reads the customer from the **signed** app-proxy request, never from IDs the browser sends. A logged-in shopper cannot read or change another customer's wishlist by editing a request.

## Shop metafields

All metafields live in the app-owned namespace `$app`.

| Key | Storefront access | Holds |
| - | - | - |
| `cb_wishlist_widgetsettings` | Public read | Colors, labels, positions, custom CSS/JS and per-language translations |
| `cb_wishlist_featuressettings` | Public read | Feature toggles such as `Wishlist_Page` and `Collection_Page_Icon` |
| `cb_wl_tpl_page`, `cb_wl_tpl_card`, `cb_wl_tpl_item` | — | Custom page templates (one per slot) |
| `cb_wl_tpl_css` | — | Custom template CSS |
| `cb_wl_tpl_config` | Read by Liquid | Template content hash, emitted as `window.cbTc` |
| `cb_wishlist_exportcolumns` | — | Admin export column choice |

> [!NOTE]
>
> These metafields belong to the app. Change them from the Codebeans Wishlyst admin, not by writing to them directly. The app overwrites them whenever settings are saved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.