KahunaCart documentation

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

Read in this order

Get running

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

Build the store

3. Products and catalog — products, product types, variants, stock, priced add-on options, catalog order and featured products, categories, tags, attributes, related products, images, and downloadable files.
4. Storefront — routes, template overrides, Twig functions, search and its three engines, instant filters, pagination, sectioned listings, SEO output, and the checkout flow.
   • Shortcodes — put a product grid, a buy button or a gallery into an ordinary page's Markdown, with no Twig in content and no theme change.
5. The catalog index — the index behind every listing, facet count, sort and ranked search, when queries use it, and how to rebuild it.
6. Customer accounts — the account area, store accounts, invoices, and the address book.
7. Address validation — the optional address check at checkout, with Google or Mapbox.
8. Theming — the --kahunacart-* custom properties and CSS class reference.
   • Theme blocks — change a storefront page's markup by extending it instead of copying it.
9. Multilanguage — translated catalog text and language-prefixed routes. Skip on a single-language store.

Get the money right

10. Tax — flat rate or zones, tax classes, inclusive pricing, and the EU VAT preset.
11. Shipping — flat rate or zones, methods, shipping classes, and free-shipping thresholds.
12. Coupons — coupon types, the discount basis, stacking, campaigns and bulk code generation, the restriction matrix, and conditions that keep a code to a customer group or to a cart that holds a given product.
13. Sales — automatic scheduled discounts, rule precedence, quantity tiers, the storefront badge, and how sales interact with coupons.
14. Price lists and quantity tiers — quantity discounts, price lists, customer eligibility rules, the selection algorithm, and current storefront support.
15. Rules and conditions — the operations a discount prices through, the condition vocabulary, buy-one-get-one, and registering your own.
16. Money conventions — every amount is stored in minor units, and how a per-line refund is allocated.
17. Currencies: sell in more than one currency: the settings, typing a price in each or converting from the base price, exchange rates, how the shopper's currency is chosen, what a missing amount does, switching with a cart open, reports, caching and the add-ons.
    • Selling through more than one company: a company per currency, with its own invoice and credit-note books and its own payment account.
18. Store credit, gift cards and credit notes — one append-only ledger with the balance summed and never stored, gift cards on top of it, spending credit at checkout, refunding to credit, and the numbered credit note every confirmed refund earns.

Sell and deliver

19. Payment providers — Stripe, Polar, PayPal, and the offline provider.
20. Payment methods — several checkout options for one gateway: labels, logos, instructions, a taxed fee, and conditions that decide when each is offered.
21. Digital products — files, download grants, delivery methods, and refunds.
22. Product releases — versioned builds, publishing from CI, and who gets which version.
23. Licenses — license keys, seats, updates windows, renewals, and the public validation API. Add-on.
24. Catalog sync — keeping a provider's catalog in step with yours.
25. Subscriptions — plans, billing modes, trials, renewal orders, and the customer and admin screens. Add-on.

Run it

26. Orders and the admin — order status, the indexed order search, order history and notes, shipments and packing slips, refunds, bulk actions, the configurable export, and quotes.
27. Order statuses — the three configurable status categories, the flags used by reports and add-ons, and how to add or rename a status.
28. Order changes — editing a placed order by staging a change and confirming it, the version that keeps every earlier state readable, returns including damaged units, and the audited unlock.
29. Customers, wishlists, reviews and retention — customer groups and the codes used in rules, named wishlists, reviews with a computed verified badge, the four-window retention schedule, and reassigning or erasing a customer.
30. CLI — every bin/plugin kahunacart command.
31. Reports and the rollup — the daily rollup the sales reports read, when its numbers are exact, and how to rebuild it.
32. Analytics — comparison periods, published metric definitions, filters and breakdowns, where an order came from, and cost of goods and margin.
33. Dashboard alerts — the strip at the top of the admin, the four checks that ship, hiding one, and registering your own.
34. Importing — the CSV importer for products, variants, categories, customers and orders, with saved mappings, dry runs, resumable runs and error reports.
35. Export and restore — the whole store in one zip and back: what a bundle holds and leaves out, customer password hashes and the keys sealed with a passphrase, full restore or merge, the dry run and the report, and moving a shop to a site of its own.
36. Emails — the sixteen customer emails, resending one, and how to override their templates.
37. Object templates — editable Twig templates for SKUs, line titles, the order reference, invoice file names and email subjects.
38. Notifications — get told about your store by email, Slack, Discord, Telegram, Pushover, ntfy, Gotify, text message or a webhook.
39. Hardening — web-server rules for the data directories, expiring order links, rate limits, trusted proxies, and reporting a vulnerability.
40. Troubleshooting — symptoms, causes, and fixes.
41. Benchmarking — seed a quarter of a million orders and time the queries behind the storefront and the admin.
42. Performance — PHP-FPM, opcache and database settings for production, and where to start investigating slow performance.

Mail the list

43. Newsletters — what the add-on is, what it needs, and the ten screens it adds to the admin.
44. Getting started with the newsletter — install, the From address, the first list, the signup form and the first campaign.
45. Subscribers, lists and tags — consent and confirmation, the five statuses, the preference centre, suppressions, and CSV import and export.
46. Segments — saved filters for your audience, the condition vocabulary, and how counts refresh.
47. Campaigns — writing, previewing, testing, scheduling, A/B subject tests, UTM tagging, and where each number comes from.
48. Automations — the ten triggers, the six kinds of step, the three recipes, and how steps run once per minute.
49. Reports — seven reports over a date range: campaign performance, list growth, engagement, links, bounces and complaints, automations and send times.
50. Health — the nine deliverability checks over your domain, your transport and the last thirty days of sending.
51. Delivery reports and providers — the provider webhook, what the store does with each event, and how reports are matched to messages.
52. Settings reference — every newsletter config key with its default.
53. Newsletters for developers — the storefront routes, the admin API, the events, the Twig function and the two registries.

Automate it

54. Run the store from an AI assistant — connect grav-mcp, check the connection, and every KahunaCart tool an assistant can call.

Sell through AI agents

55. Agentic commerce — the four parts that let AI shopping agents find and buy from the store, what an agent can and cannot do, and the setup checklist for Google AI Mode and Gemini, ChatGPT and MCP clients.
56. Product feeds — the Google Merchant Center and OpenAI feeds: which products are rows, every field, and when the files are built.
57. Storefront MCP — the public MCP server at {base}/mcp and its thirteen tools.
58. UCP checkout — native checkout for Google's agents: the profile, sessions, Google Pay with Stripe, the continue_url handoff and signed order webhooks.

Extending KahunaCart

• Provider contract — the specification a payment provider plugin implements.
• Provider developer guide — build a provider plugin step by step.
• Admin sections — add your own screen to the KahunaCart admin.
• REST API — authentication, conventions, permissions and every endpoint, for integrators and CI pipelines.
• Events — every event the base plugin, Licenses and Subscriptions fire, with their payloads.
• Twig functions and filters — the storefront's Twig helpers with their signatures.
• Shortcodes — the six storefront blocks a page's Markdown can carry: a product grid, a buy button, a gallery, no Twig in content.
• Signed links and rate limits — order links, tokens, the rate-limit buckets and trusted proxies from a developer's side.
• Extension zones — the named locations where add-ons can display widgets in the admin and storefront.
• Storefront JSON API — the public JSON endpoints beside the HTML pages, for a headless front end.
• Outbound webhooks — subscriptions that tell another system when something happens here.
• Translating KahunaCart — translating the plugin, and how to submit a pack.
• Custom fields and the settings store — typed fields on a record, and the namespaced settings tier an add-on stores its own keys in.
• Publish your plugin's tools to an AI assistant — describe your own routes in an mcp.yaml manifest.

Quick reference

Known limitations

Each limitation below is also described on the relevant guide page.

• A currency no rate source lists needs a rate you type. The European Central Bank lists about thirty currencies, and Frankfurter, which is asked for the rest by default, lists more than 160. For a currency neither lists, type the rate on the Currencies screen or use a source from an add-on. A currency set to convert with no rate stays unpriced. See Currencies.
• Catalog sync creates the default variant only. Extra variants are recorded in the mapping row, not created at the provider. See Catalog sync.
• An unallocated partial refund reverses nothing. A refund that names its lines restocks them and revokes their downloads; a refund that is only an amount cannot tell which items the money was for. See Orders and the admin.
• A shipment cannot be deleted or voided. Recording one is the only write, and an under-shipment is corrected by shipping the remainder. Shipment records and download revocations cannot be reversed. 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.
• Returns have no exchanges yet. A customer who wants a different size returns the first one and places a new order. See Returns.
• A status you add cannot mean "the payment was refused". The registry has no column for it, so a second refused-payment status is swept by the trash pending retention rule rather than the failed one. See The retention schedule.
• An imported order records no adjustments, taxes or shipping lines. The file's own total is stored as authoritative, so an imported order's totals need not add up from its lines. See Importing.
• Only Stripe charges Google Pay for an agent. Every other provider, PayPal included, sells to agents through the continue_url handoff to your own checkout. PayPal's Google Pay support is planned for a later phase. See UCP checkout.
• ChatGPT's in-chat checkout (ACP) is not built. OpenAI dropped in-chat checkout in March 2026. The OpenAI product feed is built, and a ChatGPT buyer buys on your product page. See Agentic commerce.