Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

Product lifecycle

KahunaCart saves a revision after every product edit, so you can restore an earlier version. You can also schedule publication and price changes, or require customers to buy one product before they can buy another. This page explains these tools for store administrators.

Before you begin

  • The background worker has to be running for anything scheduled to happen. See CLI → work and Going live.
  • Revisions are on by default and capped at 20 per product.

What a revision holds

KahunaCart snapshots a product every time you save it. The snapshot holds every row the product owns, with its ids, so a restore puts things back exactly where they were.

In the snapshot Not in the snapshot
The product row, variants, options and their values, per-variant option combinations Product files and releases
Option prices, quantity tiers, media rows Price-list prices
Categories, tags, attributes (product and per-variant) Reviews, wishlists, stock holds
Kit children, related products, translations, custom-field values Order lines that reference the product

Stock is never restored for a variant that still exists, so restoring a revision does not reverse stock deductions from later sales. A variant that was deleted and comes back with the restore keeps the snapshot's figure.

Files and releases are not restored. They point at bytes on disk that may have been removed since.

Restore a product to an earlier version

  1. Open the product in the admin.
  2. Read the revision list. Each row says when, who, and what wrote it.
  3. Press Restore on the version you want.

The product returns to the saved state, and a new revision records the restore. Existing revisions remain available, including the version you restored from.

A restore is refused with a 409 when the revision's slug now belongs to a different product. Rename that product first.

How many revisions are kept

catalog.revisions.keep sets how many revisions each product keeps. The default is 20. The background worker prunes each product back to the cap once a minute. Set it to 0 to switch revisions off: no snapshot is taken and Restore has nothing to offer.

A queued change is never pruned, however old it is. Dropping one would silently cancel next month's price.

Schedule a product to go live

A product carries a publish time and an unpublish time, both stored as UTC epoch seconds.

  1. Open the product in the admin.
  2. Set Publish at to the time it should appear.
  3. Save.

The product goes to Draft immediately. At its time the background worker publishes it and marks it dirty on the catalog index in the same tick, so it is on the storefront within one minute.

Unpublish at does the reverse and moves the product to Draft, not Archived.

catalog.schedule.enabled (default true) decides whether the worker acts on the publish window and on queued changes at all. Turn it off and the times stay on the products without being acted on.

Note

All times are UTC epoch seconds, like every other timestamp KahunaCart stores. The store has no timezone setting of its own, so an admin client converts to and from your local time.

Queue a price change

A scheduled change is a revision with a time on it. There is no second system.

  1. Read the product as it should be at that time.
  2. Queue it with a time.
  3. The worker applies it at that time by restoring it.

Applying a queued change also writes a revision, so the change that landed at midnight is in the list beside every hand edit.

A queued change is claimed before it is applied, so two workers on the same tick cannot both apply it. A change whose product has been deleted, or whose slug now belongs to another product, is marked as reached and left unapplied.

Require an earlier purchase

A product can require another. The storefront refuses to add it to a cart until the shopper has a completed order carrying what it names. Use it for an upgrade, part two of a course, or a paid add-on.

  1. Open the product in the admin.
  2. Under Requires an earlier purchase, add the products that have to have been bought.
  3. Choose Any one of them for an upgrade path from several earlier editions, or All of them for a sequence.
  4. Save.

Adding the product to a cart is now refused with a message naming the required product and linking to it. Set message_key on a rule to use wording of your own.

Only a completed order counts

Order state Satisfies a prerequisite
A status flagged complete, including your own Dispatched or Collected Yes
A status flagged new, so a cart, a pending order, your own Awaiting artwork No
A status flagged cancelled No

Which statuses count comes from the order-status registry and its complete flag, never from the word "completed". A store that adds statuses of its own gets the answer its own board implies.

Who the shopper is

A signed-in customer is checked against their account's orders. A guest is checked against the orders their browser session remembers placing, which stops working when they clear their cookies.

Checked twice

The rule is enforced at add-to-cart and again at checkout, inside the transaction that takes the stock. This catches a cart filled before you set the rule.

Important

A prerequisite naming a product that has since been deleted refuses the add-to-cart rather than being dropped. Delete the rule, or restore the product.

API reference

All five routes need kahunacart.products.manage, and each has an MCP tool that takes the same arguments.

Route MCP tool What it does
GET /kahunacart/products/{id}/revisions list_product_revisions The product's revisions, newest first, plus its publish window
POST /kahunacart/products/{id}/revisions/{revision}/restore restore_product_revision Restore that revision and write a new one
PUT /kahunacart/products/{id}/schedule set_scheduled_publish Set or clear publish_at and unpublish_at
GET /kahunacart/products/{id}/prerequisites list_product_prerequisites The product's prerequisites, with the required products' titles
PUT /kahunacart/products/{id}/prerequisites set_product_prerequisites Replace them wholesale. An empty list clears them

See Products in the REST API for the full request and response bodies.

Configuration

Key Default Effect
catalog.revisions.keep 20 How many revisions each product keeps. 0 switches revisions off
catalog.schedule.enabled true Whether the worker acts on publish_at, unpublish_at and queued changes