# Kirby Kart
> A streamlined, lightweight e‑commerce and shopping cart plugin for [Kirby CMS](https://getkirby.com) (v5+).

Github: https://github.com/bnomei/kirby-kart
Current Version: v5.10.5
Website: https://kart.bnomei.com
Buy: https://buy-kart.bnomei.com
Demo: https://kart.bnomei.com/demo
Theme: https://kerbs.bnomei.com
Author: [Bruno Meilick](https://github.com/bnomei)

## Overview

### Core Capabilities
- Syncs product data and pricing from external payment providers (e.g., Gumroad, LemonSqueezy, Mollie, Paddle, PayPal, Snipcart, Stripe, SumUp) into Kirby.
- Optionally, products can be defined directly within Kirby, using providers solely for checkout.
- Orders, stock, and fulfillment are managed within the Kirby Panel.
- Supports hooks to extend the fulfillment flow (e.g., sending emails, generating PDFs).

### Checkout Features
- Secure payments with CSRF protection, rate limiting, CAPTCHA support.
- Guest checkout or automatic account creation via “magic link” emails.
- Carts and wishlists persist across sessions and merge on login.

### Developer-Friendly Integration
- Not a full theme—maintains control over content structure.
- Built using Kirby-native tools: snippets, blueprints, PHP logic, hooks.
- Panel includes localized UI plus statistics, caching, SEO‑friendly JSON‑LD, Discord notifications, environment variables, HATEOAS API support, global messages, Gravatar integration, and optional Kerbs starter theme.

### License and Trial
- Commercial plugin. Works locally without license.
- Requires purchased license in staging/prod; validated against licensing server.
- License keys may be managed via .env and config.

## Documentation

### Setup
- [Introduction](https://kart.bnomei.com/docs/setup/introduction.md): Add a shop to your Kirby CMS website with Kirby Kart: cart, wishlist, product sync with 10 payment providers, magic links, captcha & headless support
- [Installation](https://kart.bnomei.com/docs/setup/installation-with-composer.md): Kirby Kart plugin for Kirby CMS 5+, easily install via Composer, ZIP or Git submodule. Use custom folder setup for secure sites and smooth updates.
- [Localhost Demo](https://kart.bnomei.com/docs/setup/localhost-demo.md): Kirby Kart plugin demo: init via /kart, auto-generates products, orders & stock pages; list/filter products, view details, mock payment, and order workflows.
- [Try and Buy](https://kart.bnomei.com/docs/setup/try-and-buy.md): Try Kart plugin free locally, then buy a license for staging & production. Manage your KART_LICENSE_KEY via .env for seamless activation and full features.
- [Prefabs](https://kart.bnomei.com/docs/setup/prefabs.md): Learn how to build a custom Kirby shop frontend by copying content files, snippets, templates, blueprint tabs, models and providers with the Kirby Kart plugin.
- [Configuration](https://kart.bnomei.com/docs/setup/configuration.md): Configure Bnomei Kart plugin for Kirby CMS: license, crypto, captcha, currency, customers, orders, products, middleware, router, stock & provider settings.

### Content
- [Products](https://kart.bnomei.com/docs/content/products.md): Kirby Kart lets you sync products & prices from PayPal/Stripe, manage images, data fields & filters, auto/manual updates, JSON-LD & product variants.
- [Categories and Tags](https://kart.bnomei.com/docs/content/categories-and-tags.md): Learn how to use the Kirby Kart plugin for categories, tags, related products, URL-param filtering, and performance-boosting caching in your Kirby CMS store.
- [Cart and checkout](https://kart.bnomei.com/docs/content/cart-and-checkout.md): Kirby Kart plugin docs: cart API methods, listing, adding/removing products, variants, stock management, checkout, tax, abandoned carts, JSON-LD schema.
- [Orders](https://kart.bnomei.com/docs/content/orders.md): Kirby Kart plugin: manage orders with auto-increment invoice numbers, secure signed URLs, file downloads, license keys, hooks and customizable blueprints.
- [Wishlist](https://kart.bnomei.com/docs/content/wishlist.md): Wishlist management with Kart in Kirby CMS: list products, add, remove, toggle items, save for later or move to cart, and merge guest/customer wishlists.
- [Stock](https://kart.bnomei.com/docs/content/stock.md): Kirby Kart stock management: unlimited default stock, variant fallback, cart & checkout checks, wishlists, Panel updates, optional holds & locking queue.
- [Customers](https://kart.bnomei.com/docs/content/customer-user-accounts.md): Kirby Kart auto-creates customer accounts on checkout, assigns roles, offers cart, orders & wishlist methods, soft deletes, and stores customer data in CMS.
- [Kart](https://kart.bnomei.com/docs/content/kart.md): Discover comprehensive Kart API data: categories, tags, products, carts, orders, authentication, currency, formatting, encryption & utility methods in Kirby CMS

### Forms
- [Login and Logout](https://kart.bnomei.com/docs/forms/login-and-logout.md): Secure login/logout PHP snippets for Kirby CMS Kart: email & password form, hidden redirect, anti-double-submit button for seamless authentication flow.
- [Magic link](https://kart.bnomei.com/docs/forms/magic-link-login.md): Implement passwordless login & signup in Kirby CMS using Kart plugin’s magic-link auth: configure methods, custom forms, email settings & sending links.
- [Turnstile CAPTCHA](https://kart.bnomei.com/docs/forms/turnstile-captcha.md): Integrate Cloudflare Turnstile CAPTCHA in Kirby CMS: include JS snippet, configure site & secret keys, render widget, secure forms & validate tokens server.
- [Simple CAPTCHA](https://kart.bnomei.com/docs/forms/simple-captcha.md): Add Simple Captcha to Kirby CMS forms. Configure image style, use snippet or Alpine.js refresh, and secure login, signup, and magic-link routes with CSRF.
- [Ratelimit](https://kart.bnomei.com/docs/forms/ratelimit.md): Secure your Kart plugin endpoints with default 60 requests/min rate limit, encrypted IP storage. Excess requests return HTTP 429 errors until one hour passes.
- [Delete Account](https://kart.bnomei.com/docs/forms/delete-account.md): Soft-delete user accounts in Kirby Kart: change role to “deleted”, reset passwords, add a deletion form snippet, and hook “kart.user.softDeleted” for actions.
- [Headless and HATEOAS](https://kart.bnomei.com/docs/forms/headless-and-hateoas.md): Guide to using Kirby Kart plugin: integrate HTML forms or headless apps with JSON/CSRF, and leverage HATEOAS via Htmx for dynamic cart and wishlist interactions

### Data
- [Security](https://kart.bnomei.com/docs/data/security.md): Secure your Kirby CMS: disable endpoints under attack, enforce HTTPS, protect .env, set CSP headers, configure server rules, disable debug mode.
- [Data stored in the CMS](https://kart.bnomei.com/docs/data/data-stored-in-the-cms.md): Kirby CMS Kart plugin stores customer IDs, carts, orders, and caches API calls for products, prices, and security, boosting performance and data protection.
- [Performance](https://kart.bnomei.com/docs/data/performance.md): Optimize Kirby Kart performance using a specialized UUID cache driver (kart-uuid) or Turbo plugin for fast UUID-ID lookups beyond 200 products.
- [Backup](https://kart.bnomei.com/docs/data/backup.md): Kirby Janitor plugin: automate backups via CLI/cron to bypass PHP limits; schedule transfers to AWS, GoogleDrive, Dropbox; ensure .htpasswd files are included.

### Guides
- [Hooks](https://kart.bnomei.com/docs/guides/hooks.md): Kirby Kart plugin hooks for cart, wishlist, user, stock, license, error handling, plus Kirby fatal-error callback setup for notifications be it Discord or email
- [Sending Emails](https://kart.bnomei.com/docs/guides/sending-emails.md): Optimize Kirby CMS email delivery: choose third-party SMTP services, configure env files, test with MailHog, BIMI icons & build responsive emails with MJML.
- [Gravatar](https://kart.bnomei.com/docs/guides/gravatar.md): Display registered users' Gravatar images in your Kirby CMS frontend using Kart plugin helpers. Server-side caching for 24h boosts performance.
- [OAuth Login](https://kart.bnomei.com/docs/guides/oauth.md): Allow OAuth logins by disabling automatic user creation and adding custom authentication. Configure roles via kart.customers.roles to match user blueprints.
- [Discord Notifications](https://kart.bnomei.com/docs/guides/discord-notifications.md): Easily send notifications to Slack or Discord from your Kirby site using a custom webhook. Use this plugin code to automate workflows and user alerts.
- [Multiple roles for customers](https://kart.bnomei.com/docs/guides/multiple-roles-for-customers.md): Kirby Kart plugin supports multiple user roles; configure roles (customer, member, admin) in config.php. First role is the default for auto-created accounts.
- [Customer Count](https://kart.bnomei.com/docs/guides/customer-count.md): Kart plugin’s Stats Report for Kirby displays cached customer counts in the Stats section, auto-updating on user creation, deletion or role changes.
- [Logging](https://kart.bnomei.com/docs/guides/logging.md): Discover Kirby CMS logging methods: plugin options (kirby-logger, monolog) or external services like New Relic and Sentry. Leverage Kart hooks securely.
- [Set and flush global messages](https://kart.bnomei.com/docs/guides/set-and-flush-global-messages.md): Set and flush global session messages in Kirby CMS with PHP: add, display, and remove user messages using code examples for dialog popups.
- [Migration from Merx](https://kart.bnomei.com/docs/guides/migration-from-merx.md): Learn how to migrate your Merx shop to Kirby Kart with seamless product syncing, media handling, tax/order adjustments and expert troubleshooting tips.
- [Translation / Languages](https://kart.bnomei.com/docs/guides/translation-languages.md): Help translate the Kart plugin’s Panel into supported languages. Submit errors or new languages via GitHub PR to earn discount codes and free licenses.
- [Exclusive Content](https://kart.bnomei.com/docs/guides/exclusive-content.md): Unlock content with one-time purchases using Kirby Kart. Customize Stripe checkout options and create subscriptions with full checkout control.
- [Installing Kart with AI](https://kart.bnomei.com/docs/guides/installing-kart-with-ai.md): Kirby Kart plugin provides llms.txt for fast LLM content discovery and integrates MCP servers to boost AI code suggestions in VSCode & ChatWise

### Providers
- [FastSpring](https://kart.bnomei.com/docs/providers/fastspring.md): Learn how to integrate FastSpring with Kirby CMS using Kart: set provider, define virtual fields, add API creds & customize checkout via callbacks.
- [Gumroad](https://kart.bnomei.com/docs/providers/gumroad.md): Use Gumroad with Kirby Kart: fetch single products, define virtual fields, redirect to hosted checkout, and configure API credentials via config or .env.
- [Kirby](https://kart.bnomei.com/docs/providers/kirby.md): Kirby Kart’s default kirby_cms provider enables local product management with easy provider swaps, cloud checkout integrations, and custom payment templates.
- [LemonSqueezy](https://kart.bnomei.com/docs/providers/lemonsqueezy.md): LemonSqueezy provider for Kirby CMS Kart plugin: sell single products via buy-now checkouts. Configure in config.php, set API keys & customize checkouts.
- [Mollie](https://kart.bnomei.com/docs/providers/mollie.md): Integrate Mollie with Kirby CMS Kart: configure provider & secret key, customize via callbacks, collect customer email for automated account creation.
- [Paddle](https://kart.bnomei.com/docs/providers/paddle.md): Configure Kirby Kart with Paddle: provider & virtual fields, API keys, checkout URL, JS snippet, callbacks, metadata mapping, price-based variants.
- [PayPal](https://kart.bnomei.com/docs/providers/paypal.md): Integrate PayPal payments in Kirby CMS with bnomei.kart: set API credentials, sandbox/production endpoints, virtual fields, and customize checkout via callbacks
- [Square](https://kart.bnomei.com/docs/providers/square.md): Alpha Square provider for Bnomei Kart plugin: configure in site/config/config.php, set SQUARE_ACCESS_TOKEN, LOCATION_ID (.env), customize checkout via callbacks
- [Snipcart](https://kart.bnomei.com/docs/providers/snipcart.md): Integrate Snipcart with Kirby CMS using the Kart plugin: configure the provider in config.php, set API credentials in .env, and add checkout JS.
- [Stripe](https://kart.bnomei.com/docs/providers/stripe.md): Configure Stripe in Kirby Kart plugin: set test & live secret keys, virtual fields, custom checkout, customer portal, metadata mapping & variants from prices.
- [SumUp](https://kart.bnomei.com/docs/providers/sumup.md): Integrate SumUp payments with Kirby CMS using the Kart plugin: configure provider and API keys, include SumUp Checkout JS, and manage customers in sessions.
- [Chargebee](https://kart.bnomei.com/docs/providers/chargebee.md): 
- [Checkout](https://kart.bnomei.com/docs/providers/checkout.md): 
- [InvoiceNinja](https://kart.bnomei.com/docs/providers/invoiceninja.md): 
- [Polar](https://kart.bnomei.com/docs/providers/polar.md): 
- [Shopify](https://kart.bnomei.com/docs/providers/shopify.md): 

### Kerbs Theme
- [Kerbs Theme](https://kart.bnomei.com/docs/kerbs-theme.md): Kerbs is a Svelte5 shop frontend for Kirby Kart with Pico.css styling, CSS-based theme tweaks, layouts/blocks support, SEO-ready, easy setup.