Side Cart — laboratory guide

Updated for 0.1.0-alpha.57, 20 September 2026. This is a development version; beta acceptance remains open. Use a test WooCommerce site. Verified stacks include WordPress6.8/WooCommerce10.6.0 and WordPress7.1.1/WooCommerce11.1.0, both on PHP8.2.29. Classic and Blocks browser orders, native roles and lifecycle have recorded tests; this is not a claim about all hosting, themes or PHP versions.

First setup

Open HookSpark → Side Cart → Cart & appearance. Side Cart, the floating button, automatic opening, shipping progress and suggestions are off by default. Select a template and an entry point, review the preview, then enable Side Cart and publish when ready.

Save draft stores your work without changing the published configuration. Publish applies the validated configuration. Restore previous restores the previous published configuration; it does not roll back WooCommerce prices, orders or tax settings. If validation fails, correct the indicated field. Your submitted values remain on screen. If WordPress rejects a draft or publish save, Side Cart shows an error and retains the submitted fields so you can retry. A failed restore shows a separate error; it does not save your unsaved form edits.

Appearance and preview

Essential uses familiar product rows. Boutique gives images and details more space. Compact concentrates information for longer carts. Drawer and Modal show the same cart; a drawer can open from the right or left. Fonts come from your theme, without a remote font service added by Side Cart.

The preview uses sample data and the same cart renderer. Try desktop and mobile widths, an empty cart, a stock error and long personalization details. Preview controls cannot place orders or change the real cart. Always test the storefront too.

Under Text, colors and sizing, customize the heading, checkout and continue-shopping labels, empty-cart text and service information. Blank fields use defaults. Text must be plain text, without HTML. Labels allow up to 120 characters, service information 240 and URLs 500. A service link requires both text and a valid HTTP/HTTPS address.

Desktop width accepts 320–960 pixels, bounded by the available screen space. Mobile product images are on by default and can be hidden. Set panel background/text and checkout-button background/text as pairs: explicit color pairs must reach a 4.5:1 contrast ratio. This validation does not certify the accessibility of your entire theme.

Cart entry points and visibility

Use a floating button, a classic menu location, the Side Cart link block or [hs_smart_cart] in a supported shortcode area. Keep a native WooCommerce cart link as a fallback. Side Cart does not automatically replace theme or builder drawers; choose one primary cart overlay to avoid duplicate openings.

Choose the floating button’s left or right side independently from the drawer. Bottom spacing accepts 0–300px (default 18px), adds to the native Storefront mobile-bar clearance and is capped in short viewports. Adjust it around chat, consent banners and sticky bars, then check the storefront: the preview shows the cart panel. Publish to apply.

Open after a successful addition is optional. It works with the tested native add-to-cart paths, including WooCommerce forms that reload the page. The latter use a functional hs_sc_added_ cookie lasting at most one minute, without cart contents or customer details. Manual opening remains available if the browser blocks this cookie.

Choose whether to show Side Cart throughout the site, on catalog surfaces or on product pages. Excluded pages accepts up to 100 pages, including Shop. Publish to apply changes. The cart and checkout pages are always excluded from the overlay; manual links retain the native WooCommerce destination. Remove a page from the exclusion list and publish to enable the overlay there again.

Empty cart

Browse products links to the WooCommerce shop by default. Under Text, colors and sizing, change its label and destination—for example, to a collection page. Leave fields blank for defaults. A custom destination must be a full HTTP/HTTPS URL. The empty preview shows the result without navigating. Publish to apply it. Checkout remains unavailable while the cart is empty.

Quantities, options and recovery

After editing a quantity, use Update quantity. Checkout is unavailable through the panel while an unconfirmed quantity differs from the server value. WooCommerce remains authoritative for prices, discounts, taxes, stock and limits. The panel reconciles after responses and supported updates from other tabs.

Personalization appears in the product row. Longer detail sections can be collapsed; their state is retained during recalculation of that row. Products with different customizations remain separate cart lines. Editing complex options or switching a row's variation inside the panel is not included: use the product configurator to make a new selection.

Remove removes the selected row. Undo revalidates whether the product can still be purchased and may be refused if stock, options or session state have changed. Out-of-stock products have a panel message and a row-level message; remove the affected item to continue. Quantities sharing an inventory owner are considered together. WooCommerce may correct quantities and totals when stock decreases. External inventory providers need dedicated testing.

Expand Have a coupon? to enter a code. An error leaves the input available for correction. Applied coupons can be removed individually. Totals reflect WooCommerce responses; shipping that cannot yet be calculated is not presented as free.

If a write request cannot be confirmed, editing actions are paused. Use Refresh cart to retrieve the server state before trying again. If the problem persists, View full cart provides the native WooCommerce route. A missing confirmation does not necessarily mean the change failed.

Free shipping and product suggestions

Shipping progress reads native WooCommerce methods, destination, zone, thresholds and coupon conditions. It may remain hidden until an applicable reward can be determined, and stays hidden for digital-only carts. Removing a coupon or changing quantity can change progress or revoke free shipping. Custom shipping providers are not automatically supported.

Choose Selected products or WooCommerce cross-sells for suggestions. Select up to 30 manual candidates in display order; at most three eligible products appear. There may be fewer or none. Unavailable, unpurchasable and already-added products are excluded. These relationships are not presented as purchase statistics.

For a standard variable product, select all attributes and wait for price and availability before adding it. Unavailable combinations cannot be added. When required customizations need the product configurator, Choose options opens that product. Final cart prices include applicable rules. Suggestions never add products automatically.

HookSpark integrations and languages

Integrations shows local activation status and links. An active plugin does not certify every combination. Product Options & Add-Ons owns configurations and surcharges; MinMax owns quantity constraints; Pricing owns discounts; Messages owns its messages. Avoid duplicate shipping indicators when using Messages. Tested versions and economic scenarios are linked from the feature specification (FEATURE_SPEC.md).

HookSpark plugins shows the shared catalog. Visiting it does not install or activate products. Available actions depend on permissions and product status.

Side Cart's own strings are available in English and Italian. Storefront language follows the site; administration follows the user profile. Merchant content, product names and strings from WooCommerce, themes and other plugins use their respective content and translations. Saved custom labels are not translated automatically.

Diagnostics and removal

Start here checks the published activation state, assigned checkout page and native cart surfaces in block-theme templates, synced patterns and active widgets. Inspection has depth and size limits and does not automatically cover builders or dynamic patterns. A published checkout page does not prove its form and payment method work: place a test order. No detected Mini-Cart block does not rule out builder, widget or third-party drawers.

The technical report is collapsed by default. Download diagnostics creates a local file containing versions, plugin status and checks. It excludes customer data and tokens and is not sent automatically. Review it before sharing it with support.

Deactivation preserves settings and leaves products, coupons and orders with WooCommerce. Reactivation restores the published configuration. Before removing the plugin permanently, replace its blocks and shortcodes with native cart links where needed.

Settings are retained on uninstall by default. To remove them, open Data retention, enable Delete Side Cart settings when uninstalling, and Publish. Saving a draft alone does not change this policy. To revoke the choice, turn it off and publish again. Deleting the plugin then removes only Side Cart's draft, published and previous settings. Orders, products and WooCommerce data remain. Default retention and explicit deletion have been tested in the single-site laboratory; multisite is not certified. Keep a consistent file/database backup before permanent removal.

Test before use

On desktop and mobile, try simple and variable products, required options, valid and invalid quantities, coupons, remove/undo and checkout. Compare amounts and details with the resulting WooCommerce order using a test payment method without a real charge. Also test stock loss and recovery after an error.

The feature specification (FEATURE_SPEC.md) is the status source. The beta scope (BETA_SCOPE.md), order evidence (BROWSER_ORDERS_ALPHA14.md), stock evidence (STOCK_LOSS_ACCEPTANCE.md), tax/shipping evidence (TAXED_SHIPPING_ACCEPTANCE.md), lifecycle evidence (LIFECYCLE_ACCEPTANCE.md) and developer contracts (PUBLIC_EVENTS.md) describe coverage and limitations. Universal compatibility, embedded checkout, checkout-field editing and express payment are not promised by this product.

If a stored draft is malformed, the editor uses valid published settings, or disabled defaults. Opening the editor does not overwrite stored data; publish a corrected configuration to replace it. Malformed previous snapshots are rejected without a partial restore.

Automatic opening respects another visible dialog, such as the WooCommerce mini-cart: cart data still refreshes without opening a second panel. Keep one primary cart surface configured.

Data and privacy

Side Cart uses the WooCommerce session and does not add its own customer database or analytics service. The native-addition signal is a one-minute functional cookie. Diagnostics are downloaded explicitly, without automatic submission. Store-configured images may load from external hosts. See the data inventory and verification limits (PRIVACY_ALPHA46.md) (Italian).

Changes from multiple tabs

Side Cart coordinates participating browser tabs when Web Locks is available. The current plugin also coordinates native WooCommerce sessions on the server before reading the cart and through saving it. This server protection requires one database server and a connection retained throughout the request; custom session handlers are outside its scope. If an operation times out or its result is uncertain, refresh before another change. This does not certify every cache provider, authentication transition or third-party integration.

Interrupted file update

If an update leaves files missing and WordPress cannot start, restore the entire hs-smart-cart folder from the verified package using your lab or hosting file manager. Retain a diagnostic copy and your pre-update file/database backup. Do not uninstall to repair: the published deletion option can remove settings. Check settings, cart and checkout after recovery. File-only recovery was tested on alpha52. Alpha57 also passed an isolated full files/database/media restoration, with WordPress boot, the saved order and media delivery verified. This does not provide an automatic backup service.

Service or session failures require Refresh cart; quantities and coupons are not automatically treated as invalid. A quantity draft may remain visible separately from the confirmed value; apply it only after reconciling the cart.

Sale and coupon presentation

Catalog unit prices distinguish regular and sale prices before options. This reference is separate from the personalized line total. When discounted by a coupon, the line shows its native before-coupon amount; the final line amount remains owned by WooCommerce. Suite promotions appear in metadata supplied by Pricing. Choose “Sale and coupon” in the preview for simulated data; this does not configure store promotions.

Starting values

These are the plugin defaults, not necessarily the values saved in your store.

Three practical setup checks

Boutique cart with selected suggestions

On a test store, keep a native cart link available. Choose Boutique and Drawer, then select a menu location or place a Side Cart link block. Choose Selected products and select two available simple products which are not already in the cart. Save a draft and inspect both preview widths; the preview suggestions are examples, so verify your actual selections on the storefront after publishing. Add a different product and open Side Cart: eligible selected products should appear, up to three. Add one suggestion and check that it becomes a cart line and is no longer suggested. If no suggestions appear, check purchase eligibility, stock, existing cart contents and required options before changing the selection.

Personalized digital product with a coupon

Use a virtual test product priced at €30, a required €5 per-item option, and a valid 10% coupon. For this numerical example, disable taxes and shipping in the disposable test environment only. Add two units with a completed option: the subtotal should be €70 and the coupon should reduce the total to €63. Removing the coupon should return €70. Two different option values should create distinguishable rows. Remove one and use Undo; inspect the restored option as well as the amount. If totals differ, inspect Pricing rules, tax settings and coupon restrictions rather than editing a price in Side Cart. Confirm the same details in a test order before accepting the integration for your store.

Native free shipping with a known destination

Use a physical product and an applicable native WooCommerce free-shipping method in a test shipping zone. Enable shipping progress and publish. First check the cart without an established destination: a hidden indicator is expected when Side Cart cannot determine an applicable method. Enter a destination through the native cart or checkout, return to a page where Side Cart is enabled and refresh it. Test quantities below and above your configured threshold. If the method requires a coupon, test both with and without an eligible coupon. Accept the result only if the native checkout offers the same shipping benefit; a decorative progress bar is not evidence that shipping is free.

When the result is unexpected

Page cache and session recovery

Cache only public anonymous pages. Exclude cart, checkout, account pages, WooCommerce Store API routes and POST requests. Bypass page caching for logged-in users and WooCommerce session/cart cookies, including wp_woocommerce_session_*, woocommerce_items_in_cart and woocommerce_cart_hash. Preserve private/no-store response headers and never serve cached Set-Cookie headers to another visitor. Apply equivalent rules to both pretty REST URLs and ?rest_route= URLs.

After configuring a cache, use two independent browser sessions: add different quantities and confirm each cart and checkout keeps its own total. If an operation fails because the session authorization expired, choose Refresh cart, inspect the confirmed state, then explicitly retry the intended change. Do not automatically replay a purchase or cart mutation.

Alpha57 passed a local shared-cache test with different guest carts, a genuinely expired Woo nonce and explicit recovery. This verifies the stated policy, not every CDN or object-cache provider.

Real interface screenshots

English interface, alpha.57. Template previews use sample data; storefront captures show the laboratory cart.