KahunaCart documentation

Native ecommerce for Grav 2.0 — products, cart, checkout, orders, digital delivery, and a payment-provider ecosystem.

Requirements, install, your first product, and your first sale with the built-in offline provider.

Products, variants, categories and the storefront your customers actually see.

Tax engines, shipping zones, coupons, and the minor-unit conventions behind every amount.

Stripe, Polar, PayPal and offline payment, plus digital downloads, versioned releases, license keys and catalog sync.

The admin, the CLI, emails, merchant notifications, and troubleshooting.

The provider contract, a walkthrough of building one, and adding your own admin screen.

Read in this order

Get running

Getting started — requirements, install, your first product, and a test order with the built-in offline provider.
Configuration — every config key with its default, database options, and the route cache.

Build the store

Products and catalog — products, variants, stock, categories, tags, images, and downloadable files.
Storefront — routes, template overrides, Twig functions, search, SEO output, and the checkout flow.
Customer accounts — the account area, store accounts, invoices, and the address book.
Address validation — the optional address check at checkout, with Google or Mapbox.
Theming — the --kahunacart-* custom properties and CSS class reference.
Multilanguage — translated catalog text and language-prefixed routes. Skip on a single-language store.

Get the money right

Tax — flat rate or zones, tax classes, inclusive pricing, and the EU VAT preset.
Shipping — flat rate or zones, methods, shipping classes, and free-shipping thresholds.
Coupons — coupon types, scope, limits, and usage counting.
Money conventions — every amount is stored in minor units.

Sell and deliver

Payment providers — Stripe, Polar, PayPal, and the offline method.
Digital products — files, download grants, delivery methods, and refunds.
Product releases — versioned builds, publishing from CI, and who gets which version.
Licenses — license keys, seats, updates windows, renewals, and the public validation API. Add-on.
Catalog sync — keeping a provider's catalog in step with yours.

Run it

Orders and the admin — order status, marking paid and shipped, refunds, reports, and export.
CLI — every bin/plugin kahunacart command.
Emails — the six customer emails and how to override their templates.
Merchant notifications — Slack, Discord, and signed webhooks for store events.
Troubleshooting — symptoms, causes, and fixes.


Storefront base route	`/shop` (config key `route`); `/de/shop` on a multilanguage site
Webhook URL	`{site}/shop/webhook/{provider-slug}`
Database	`user/data/kahunacart/db/kahunacart.sqlite`
Downloadable files	`user/data/kahunacart/files`
Product images	`user/images/kahunacart/products`
Category images	`user/images/kahunacart/categories`
Product search	`{site}/shop/search?q=`
Filtered listing	`{site}/shop?tag[]=organic&min=10&stock=1`
Customer account area	`{site}/shop/account` (needs the Login plugin)
Admin	Sidebar → KahunaCart (`/plugin/kahunacart`)
Health check	`bin/plugin kahunacart status`
After a plugin update	`bin/grav clear-cache`

KahunaCart 0.1.0 is marked testing: true. Each limitation below is also called out on the page where it applies.

Catalog sync creates the default variant only. Extra variants are recorded in the mapping row, not created at the provider. See Catalog sync.
Partial refunds reverse nothing. A full refund restocks, releases the coupon, and revokes download grants; a partial refund cannot tell which items the money was for. See Orders and the admin.
Shipping and revocation cannot be undone. There is no un-ship and no un-revoke. See Orders and the admin.
A merchant-of-record provider charges no local tax. This is decided when the customer picks the payment method, so the cart page still shows the local estimate. See Tax.
Stripe ships hosted Checkout only. On-site Elements is planned for a later phase.