# Cart Reserve > Build reliable apps & libraries with lightweight, composable, and type-safe modules that interface with Ethereum. ## Products The **Products** section allows you to configure **cart reservation limits** for individual products in your store. These limits control how many units of a product a customer can reserve in their cart at one time. Reservation limits are applied **per product** and automatically affect **all of its variants**, ensuring consistent behavior across different options such as size or color. ### Product List & Search * **Search products** Use the search field to quickly find products by name in the list. * **Select all / product checkbox** Select one or multiple products to manage them in bulk. * **Refresh** Reloads the product list and syncs the latest product data from your store. * **Add Products** Adds new products to the reservation management list. * **Save** Saves all configured reservation limits. ### Cart Reservation Limits For each product, you can define the **maximum quantity allowed in the cart**: * The numeric input represents the **maximum quantity a customer can reserve** for the product. * This limit applies to **all variants of the product**, regardless of their individual stock levels. The tooltip icon provides a quick explanation of how reservation limits work. ### Variants Overview Product can be expanded to display its variants: * **Variant name** – Specific product variant * **Stock** – Current available stock for the variant This overview helps you set appropriate limits based on real inventory availability while keeping reservation rules simple and product-based. ## Dashboard The **Dashboard** is the central analytics hub of the Cart Reserve app, providing a complete overview of reservation activity, session performance, security status, and customer behavior across your store. It combines real-time metrics, performance indicators, security insights, and product and geographic analytics into a single view, helping you quickly understand how reservations impact sales and inventory. At the top of the page, you can see the store domain and the date range, which applies to all displayed metrics, tables, and charts. ### Navigation Buttons Located in the top-right corner, these buttons provide quick access to key sections of the app: * **Manage Products** Redirects you to the Products section, where you can configure maximum quantities per product in cart. * **View Sessions** Opens the Sessions page, allowing you to inspect individual customer sessions and reservation details. * **Settings** Takes you to global app settings ### Metrics Cards #### Total Sessions Shows the total number of reservation sessions. The badge below indicates how many sessions are currently **active**. #### Converted Displays the number of sessions that successfully completed checkout. The conversion rate represents how effectively reserved sessions turn into purchases. #### Expired Indicates the number of sessions that expired before checkout was completed. #### Renewals Shows how many times reservation sessions were extended or renewed. The average value helps identify how often customers need more time before completing a purchase. ### Session Trends Chart The **Session Trends** chart visualizes reservation activity over time and helps you understand customer behavior patterns. #### Chart States * **Created** – New reservation sessions started * **Converted** – Sessions that resulted in a completed purchase * **Expired** – Sessions that expired without checkout * **Cancelled** – Sessions manually or automatically cancelled #### Time Filters Use the time range selector to switch between: * Today * Last 7 Days * Last 14 Days * Last 30 Days This allows you to analyze short-term spikes or long-term trends in reservation performance. ### Session Performance The **Session Performance** section provides a deeper insight into how reservation sessions behave and convert. * **Conversion Rate** Displays the percentage of reservation sessions that successfully resulted in a completed checkout. * **Expired** Number of sessions that expired before checkout * **Cancelled** Shows how many sessions were cancelled either by the system or due to validation rules. * **High Renewal Sessions** Indicates sessions that required multiple renewals, which may suggest longer customer decision times. * **View all sessions** Redirects you to the Sessions page, where you can review individual session details. ### Security Overview The **Security Overview** summarizes potential risks and security-related events detected by the reservation system. * **Total Alerts** Total number of security alerts triggered during the selected period. * **Unresolved** Alerts that still require attention or review. * **Restricted Sessions** Number of sessions that were limited or blocked due to suspicious behavior. * **Average Risk Score** A percentage-based indicator representing the overall risk level of reservation activity. * **View security dashboard** Opens the detailed security dashboard for further investigation. ### Top Reserved Products The **Top Reserved Products** table highlights products most frequently reserved by customers. Columns explained: * **Product** – Product name * **Reserved** – Number of reservation sessions for the product * **Qty Reserved** – Total quantity reserved across sessions * **Qty Sold** – Quantity successfully purchased * **Conversion** – Conversion rate from reservation to purchase Use **Manage products** to quickly navigate to product configuration and adjust product quantity limits per cart if needed. ### Geographic Distribution The **Geographic Distribution** section shows where reservation sessions originate geographically. * **Country** – Customer location based on session data * **Sessions** – Number of reservation sessions from the country * **Converted** – Number of sessions that completed checkout * **Conv. Rate** – Conversion rate by country This data helps identify regional demand and performance trends for your store. ## Help and Support ### Release ### Troubleshooting ### Contact Support ## Using Cart Reserve This guide walks you through all major features of **Cart Reserve** and explains how to configure the app to match your store’s inventory strategy, traffic patterns, and theme setup. Cart Reserve combines real-time cart reservation, session-based validation, analytics, and security controls with flexible customization options, giving you full control over how inventory is reserved and released across your storefront. ### App Navigation The Cart Reserve app is organized into **four main sections**, accessible from the Shopify Admin sidebar. Each section focuses on a specific part of the reservation system and can be explored independently. * **Dashboard** A centralized analytics view showing reservation activity, session performance, security insights, top reserved products, and geographic distribution. * **Products** Configure cart reservation limits for products and variants, controlling how many units customers can reserve per session. * **Sessions** Monitor all reservation sessions, review conversion and expiration behavior, assess risk levels, and inspect detailed session activity. * **Settings** Manage core app behavior, including product synchronization, reservation rules, storefront appearance, theme selectors, and subscription management. ## Settings The **Settings** section allows you to configure the core behavior of the Cart Reserve app, including product synchronization, reservation scope, session rules, storefront appearance, and billing. When you install the app for the first time, the Settings page appears in a **limited state**. Additional options become available once your product catalog is imported from Shopify. ### Initial Setup (First Installation) After installing Cart Reserve, you will initially see a simplified Settings page with the **Product Catalog** and **Billing & Subscription** sections only. At this stage: * No products are imported yet * Reservation features are inactive * Product-based configuration is unavailable This is expected behavior and required for proper setup. ![Cart Reserve Poduct Catalog](../../images/import_products.png) ### Product Catalog The **Product Catalog** section is required to enable inventory reservations. * **Import Products** Imports products and variants from your Shopify store into Cart Reserve. This step is mandatory before reservations can be tracked or enforced. * Once the import is completed, a confirmation banner appears showing: * Sync status * Number of imported products * Number of imported variants * **Re-sync Products** Re-imports and updates products from your Shopify store. Use this if products, variants, or inventory levels change in Shopify. ### Reservation Mode The **Reservation Mode** determines which products customers are allowed to reserve. * **All Products** All products in your store are reservable by default. * **Selected Products** Only products explicitly configured in the Products section can be reserved. This allows you to limit reservations to specific items, such as high-demand or limited-stock products. ### Reservation Settings This section controls session timing and renewal behavior. * **Session Timeout (minutes)** Defines how long items remain reserved in a customer’s cart. * **Max Session Renewals** Sets how many times a session can be renewed before it expires. > Session configuration options are currently using default values. > Custom configuration will be available in a future update. ### Storefront Templates The **Storefront Templates** section controls how reservation timers and expired states appear to customers in your theme. * Choose from multiple predefined styles * Customize labels, warning messages, and expired-state behavior * Helps match the reservation UI to your store’s design ### Theme Selectors The **Theme Selectors** section allows advanced customization using CSS selectors. * Configure how Cart Reserve identifies cart elements in your theme * Required for custom or heavily modified Shopify themes ### Billing & Subscription The **Billing & Subscription** section manages your plan and trial status. * **Choose a Plan / View Plans** Both buttons lead to the same subscription management flow. * All plans include a **14-day free trial** ## Storefront Templates The **Storefront Templates** section allows you to control how reservation-related UI elements appear to customers in your store. This includes the reservation timer, expired states, warning messages, and low-stock indicators. This section is focused purely on **visual behavior and customer-facing experience** and does not affect reservation logic or inventory rules. ### Choose a Template At the top of the page, you can select a **pre-designed template** that defines the overall style of the reservation components. Available templates: * **Default** Classic green theme with traffic-light–style states. Suitable for most stores. * **Minimal** *(Popular)* Subtle, clean design with thin borders and muted colors. * **Bold** High-contrast, attention-grabbing design for high-urgency sales. Each template has predefined colors and animations. Once selected, the template becomes the base style for all reservation states. ### Timer Customization The **Timer Customization** section allows you to fine-tune the appearance of the countdown timer for different reservation states. #### Reservation States You can switch between the following states using tabs: * **Healthy** – Plenty of time remaining * **Warning** – Time is running low * **Urgent** – Reservation is about to expire * **Expired** – Reservation has expired A **live preview** updates instantly as you adjust settings. #### Container Settings These settings control the timer container itself: * **Corner Radius** Adjusts the roundness of the timer container corners. * **Show Border** Enables or disables the container border. #### State Colors For each state, you can customize: * **Background** – Timer background color * **Text** – Label and countdown text color * **Border** – Timer border color * **Icon** – Clock icon color This allows the timer to visually match your store’s branding while keeping urgency clear. ![Cart Reserve State Color](../../images/state_color.png) ### Expired State Behavior The **Expired State** section controls what customers see when a reservation expires. You can choose one of the following behaviors: * **Inline message (in timer location)** Displays an expired message and a **Reserve Again** button where the timer was shown. * **Popup modal** Shows a modal dialog with an expiration message and action buttons. * **Banner at top of page** Displays a dismissible banner at the top of the cart page. This lets you control how disruptive or subtle the expiration message should be. ### Low Stock Warning The **Low Stock Warning** feature informs customers when they attempt to reserve more items than are currently available. * **Show warning when cart exceeds available quantity** Displays messages such as *“Only 2 available”* when stock is low. #### Warning Position You can choose where the warning appears: * **Below quantity input** Warning appears under the quantity selector. * **Above quantity input** Warning appears above the quantity selector. * **Inline with quantity controls** Warning appears next to the quantity buttons. These options help ensure the warning is visible without disrupting the layout of your theme. ## Subscription & Plans The **Subscription & Plans** section allows you to activate and manage your Cart Reserve subscription. ### Free Trial Cart Reserve offers a **14-day free trial** for all subscription tiers. * You will only be charged if you choose to continue after the trial ends * You can cancel at any time during the trial to avoid charges ### Choosing a Plan During setup, you can select a subscription plan that matches your store’s needs. Subscription tiers are designed to scale with your business and may differ in: * Reservation capacity and usage limits * Access to analytics and reporting features * Notification and alerting capabilities * Support level and response priority * Advanced customization or integration options Once a plan is selected, click **Start Free Trial** to activate it. ### Managing Your Subscription You can manage your subscription at any time: * Upgrade or downgrade your plan as your needs change * Changes take effect immediately and are prorated * Cancel your subscription directly from: * The subscription page within the app ### Billing & Payments > This section needs to be discussed ### Additional Notes Available plans, features, and limits may change over time. For the most up-to-date information, always refer to the **View Plans** section inside the app. ## Theme Selectors The **Theme Selectors** section allows you to control how Cart Reserve detects and interacts with elements in your store’s theme. This is especially useful if you are using a **custom theme**, a heavily modified theme, or a third-party cart implementation. In most cases, the default selectors work out of the box and **no changes are required**. You should only modify these settings if reservations are not updating correctly or if your theme structure differs from standard Shopify themes. ### Storefront Templates Click **Customize Templates** to open the **Storefront Templates** section. Here you can configure how reservation timers, warning messages, and expired states appear on your storefront. This section controls the **visual presentation** of the reservation system, while Theme Selectors control the **technical integration** with your theme. Use this section to: * Match the reservation UI to your store design * Adjust timer styles and expired behavior * Control how warnings and messages are displayed to customers ### Cart Item Changes Expand **Cart Item Changes** to configure how Cart Reserve detects quantity changes inside the cart. #### What this section controls * Which DOM event is used to detect cart updates (default: `change`) * Which parent container represents the cart #### When to update this section You may need to adjust these selectors if: * Quantity changes are not detected * Reservation timers do not update when cart quantities change * Your theme uses custom JavaScript or a non-standard cart layout #### How to configure 1. Identify the main cart container in your theme 2. Update the **Parent Query** selector if necessary 3. Save changes and test quantity updates in the cart ### Cart Form The **Cart Form** section defines selectors for cart page elements and checkout controls. #### Elements covered * Form Selector * Checkout Button * Quantity decrease button * Quantity input field * Quantity increase button #### Why this matters These selectors allow Cart Reserve to: * Prevent checkout when reservation limits are exceeded * Update reservations when quantities change * Maintain accurate inventory reservations during cart interactions #### Recommended approach * Start with default values * Change selectors only if checkout blocking or quantity tracking does not work correctly * After changes, test adding items, changing quantities, and proceeding to checkout ### Product Detail The **Product Detail** section controls how Cart Reserve interacts with product pages. #### Elements covered * Form Selector * Add to Cart button * Button text element * Submit Button * Quantity input and controls * Product URL path * Variant query parameter #### When this section is required You should configure this section if: * Reservations are not created when products are added to the cart * Quantity limits are not enforced on product pages * Your theme uses custom product forms or AJAX add-to-cart behavior #### How to configure 1. Open a product page in your storefront 2. Identify the correct product form and Add to Cart button 3. Update selectors if they differ from defaults 4. Test adding products and changing quantities ### Label Translations Text labels such as timer messages and button texts are managed directly by Shopify. To edit or translate labels: 1. Go to **Online Store → Themes → Customize** 2. Open **App embeds** 3. Enable **CartReserve** 4. Use Shopify’s **Translate & Adapt** app to localize labels ## Sessions The **Sessions** section provides a detailed view of all cart reservation sessions created in your store. It allows you to monitor customer activity, review session status, assess risk levels, and inspect individual session details. This section is especially useful for troubleshooting, security monitoring, and understanding customer behavior during the reservation process. ### Sessions List The sessions list displays reservation sessions for the selected store. #### Search & Filters * **Search** Search sessions by **cart token**, **IP address**, or **country**. * **Status filter** Filter sessions by their current state: * All * Active * Completed * Expired * Cancelled * **Risk Level filter** Filter sessions based on their security risk classification: * All * Normal * Monitored * Review * Restricted * **Refresh** Reloads the sessions list with the latest data. #### Sessions Table Columns * **Cart Token** – Unique identifier for the cart session * **Status** – Current session state (Active, Completed, Expired, Cancelled) * **Risk** – Security risk level assigned to the session * **Renewals** – Number of renewals used / maximum allowed * **Cart** – Number of items currently in the cart * **Country** – Customer’s country based on session data * **Actions** – **View Details** to open the session detail page ## Session Details Clicking **View Details** opens a detailed view of the selected session, providing full transparency into its lifecycle, activity, and technical data. ### Session Overview The **Session Overview** section summarizes the current state of the session: * **Status** – Current session status (e.g. Active, Expired, Converted) * **Risk Level** – Assigned risk classification * **Session ID** – Internal unique session identifier * **Created At** – Session creation timestamp * **Expires At** – When the reservation expires * **Last Activity** – Most recent interaction within the session Action buttons: * **Refresh** – Reloads session data * **Restrict Session** – Manually restricts the session if suspicious behavior is detected ### Session Metrics Provides key metrics related to the session’s activity: * **Renewals** – Number of renewals used * **Total Requests** – Total number of requests made during the session * **Line Items** – Number of products added to the cart ### Technical Details This section contains low-level technical information for security and debugging purposes: * **IP Address** – Client IP * **Location / Country** – Geographic information * **User Agent** – Browser and operating system details * **Fingerprint** – Session fingerprint (if available) * **Hash** – Internal session hash * **Referrer** – Source URL * **Accept Language** – Browser language settings ### Current Cart Displays the current contents of the cart at the time of the last session update: * **Quantity** – Reserved quantity * **Product** – Product name * **Variant ID** – Shopify variant identifier If no items are present, the cart will appear empty. ### Activity Log The **Activity Log** provides a chronological record of all important events that occur during a reservation session. It allows you to track how a session evolved over time and what changes were made to the cart. Each entry represents a specific action and includes a timestamp and the number of affected cart items. ### Activity Entries Each activity entry displays: * **Event Type** The type of action performed (for example, *Reactivated*, *Cart Updated*). * **Timestamp** The exact date and time when the event occurred. * **Item Count** The number of cart items involved in the event. ### Event Details Click **View Details** to expand an activity entry and see detailed information about the cart state at that moment. When expanded, the event shows: #### Cart Items * **Quantity** – Number of units reserved at the time of the event * **Product** – Product name associated with the reservation * **Variant ID** – Shopify variant identifier This makes it easy to understand which products were affected by a specific action and how quantities changed during the session lifecycle. import { Steps, Step } from "vocs/components"; ## Getting Started ### Overview **Cart Reserve** is a Shopify app that helps merchants control inventory availability by introducing a smart, time-based cart reservation system. Customers can reserve selected product quantities for a limited time, ensuring items remain available while they complete their purchase. This prevents overselling, reduces checkout errors, and improves overall conversion reliability—especially during high-traffic periods. For merchants, Cart Reserve provides clear visibility into reservation activity, session performance, and top reserved products, along with built-in security mechanisms that prevent abuse and excessive cart locking. The app works out of the box with standard Shopify themes and can be fully adapted to custom or advanced themes using configurable theme selectors, ensuring seamless integration across any storefront. ### Key Benefits * **Prevent overselling and checkout conflicts** Inventory is safely reserved per customer session, reducing failed checkouts and customer frustration. * **Increase purchase completion confidence** Customers know their items are held for them, encouraging them to finish checkout instead of rushing or abandoning carts. * **Full visibility and control** Track reservation sessions, conversion performance, and high-demand products in real time. * **Secure by design** Built-in validation and session limits protect your store from reservation abuse and stock locking. * **Theme-agnostic and customizable** Works instantly with popular Shopify themes and can be fine-tuned for custom storefronts using advanced selectors. ### Supported Shopify Themes For most stores, no additional configuration is required. If you are using a custom or heavily modified theme, review the **Theme Selectors** section to ensure Cart Reserve correctly detects cart and product elements. ### Installation Install **Cart Reserve** from the [Shopify App Store](https://apps.shopify.com/). To ensure Cart Reserve works correctly, complete the following steps in order. To ensure secure quantity validation during checkout, you must enable **Cart Reserve validation** in your Shopify store settings. This validation ensures that customers cannot complete checkout with quantities that exceed their active reservation or allowed limits. Follow these steps: 1. Go to **Shopify Admin**. 2. Navigate to **Settings → Checkout**. 3. Open the **Checkout Rules** section. 4. Locate **cart-checkout-validation**. 5. Click **Turn on**. 6. Save your changes. Once enabled, Cart Reserve will validate reserved quantities during checkout and prevent customers from purchasing more items than allowed. ![Checkout rules enabled](/images/checkout_rules_1.png) ![Checkout rules enabled](/images/checkout_rules_2.png) To allow **Cart Reserve** to correctly connect to your theme’s cart and product elements, you must enable the Cart Reserve app embed in your active theme. The app embed loads Cart Reserve scripts and allows the app to detect and interact with key theme components—such as cart forms, quantity controls, and add-to-cart buttons—using configured selectors. Follow these steps: 1. Go to **Shopify Admin**. 2. Navigate to **Sales channels → Online Store → Themes**. 3. Click **Edit** on your active theme. 4. Open **App embeds**. 5. Locate **Cart Reserve**. 6. Switch it **On**. 7. Click **Save**. Once enabled, Cart Reserve can apply reservation logic, track cart activity, and enforce inventory rules across your storefront. ![Shopify apps embeds](../images/app_embeds.png) Before Cart Reserve can manage reservations, your products must be synchronized from your Shopify store. Cart Reserve uses synced product and variant data to: * Track available inventory * Apply reservation limits * Validate quantities during cart updates and checkout To sync products: 1. Open **Cart Reserve → Settings**. 2. Locate the **Product Catalog** section. 3. Click **Import Products**. 4. Wait until the synchronization completes. Once the sync is complete, additional settings and features will become available. > Cart Reserve will not enforce reservation rules until products are successfully imported. For most stores, no additional configuration is required. If you are using a custom or heavily modified theme, review the **Theme Selectors** section to ensure Cart Reserve correctly detects cart and product elements. #### Installation Checklist After completing installation: * The Cart Reserve app embed is enabled in your active theme * Products are successfully synced from your store * Reservation timers and limits appear on the storefront If something doesn’t work as expected, review the **Theme Selectors** section or contact support.