Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

Getting started

KahunaCart adds native ecommerce to Grav 2.0. This page takes you from a fresh install to a completed test order.

Tip

Don't want to start from scratch? Every license comes with a ready-to-run package: a complete Grav site with KahunaCart, the Kahuna theme and a sample store already set up, with your license key written in. You'll find it in the Downloads tab of your KahunaCart account. It's also a great way to learn how to set up KahunaCart, because you can see how a working store's products, options and pages fit together. If you've bought a business theme, its ready-to-run store is there too.

Before you begin

  • Grav 2.0 or later. KahunaCart does not run on Grav 1.7.
  • The Admin plugin 2.0 or later. KahunaCart's admin screens run inside it.
  • The API plugin 1.0 or later. Every admin screen and action goes through it.
  • PHP 8.3+ with PDO. SQLite works out of the box. MySQL 8+, MariaDB 10.6+, and PostgreSQL 14+ are supported.
  • The Email plugin, for order confirmation emails and abandoned-cart reminders. It is not a declared dependency. Without it, those email jobs fail with Email plugin is not available.
  • Grav's scheduler, required for emails, download grants, expired stock holds, and cart cleanup. See Troubleshooting if these never run.

Install KahunaCart

  1. 1

    Install the license you received when you bought KahunaCart. The plugin will not install without it.

  2. 2

    Install the plugin from the admin, or with bin/gpm install kahunacart.

  3. 3

    SQLite is the default and needs no setup. To use MySQL or PostgreSQL, first configure the database, then apply the schema yourself. The default migration policy never auto-migrates a server database.

    BASH
    bin/plugin kahunacart migrate
  4. 4

    Check the result.

    BASH
    bin/plugin kahunacart status

status prints the database engine, pending migration steps, job queue counts, and every registered payment provider. A clean install lists only the built-in offline provider.

Where KahunaCart stores things

Thing Default location Config key
SQLite database user/data/kahunacart/db/kahunacart.sqlite database.sqlite.path
Downloadable files user/data/kahunacart/files downloads.path
Storefront routes /shop and everything under it route
Admin screen Admin sidebar → KahunaCart (/plugin/kahunacart) —
Plugin config user/config/plugins/kahunacart.yaml —

KahunaCart creates both data directories on first use and writes a deny-all .htaccess and an empty index.html into each. This protects Apache only.

Warning

nginx and Caddy ignore .htaccess. Run the check in Troubleshooting, and consider moving both directories outside the document root.

Your first product

A product needs a title. Every other field has a default. The price lives on the variant, not on the product. Every product gets one default variant, and a single-price product shows no variant picker.

Field Default What it does
Type physical physical or digital. Digital products skip shipping and are the ones that can carry downloadable files.
Status draft Only published products appear on the storefront.
Slug Derived from the title The public URL segment, as in /shop/product/my-widget.
Price — Set on the default variant.
  1. In the admin sidebar, click KahunaCart.
  2. Go to Products → New.
  3. Enter a Title.
  4. Set Price on the default variant.
  5. Set Status to published.
  6. Click Save.

The product is live at {route}/product/{slug}. No cache clear is needed.

To create the same product over the API:

BASH
curl -X POST https://example.com/api/kahunacart/products \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"My Widget","status":"published","type":"physical","variant":{"price":"19.99","sku":"WID-1"}}'

variant.price is a decimal string in the store currency, converted to minor units server-side. See Money conventions.

Your first sale

You do not need a payment provider to test a sale. The built-in offline provider is on by default. It places the order with payment status pending, and you mark it paid by hand when the money arrives.

  1. Visit /shop and open your product.
  2. Add it to the cart, go to /shop/cart, then click Checkout.
  3. Enter an email address and a billing address.
  4. Pick Bank Transfer as the payment method and place the order.
  5. In the admin, go to Orders and open the new order.
  6. Click Mark paid.

The order's payment status is now paid.

Note

Step 4 lands the customer on the receipt at /shop/order/{hash}. The hash is the customer's only handle on the order, so it is long and random, and nothing links to the page.

The admin sidebar badge counts completed orders still awaiting payment. To take real money, install one of the payment providers.

Turn off the offline payment method

Set offline.enabled to false. Bank Transfer disappears from checkout.