; // i18n strings
}
```
Define `adminApps` for every page your plugin exposes. Each entry requires a unique `id`, a display `label`, a Lucide `icon`, and a `component` wrapped with your `withBridge` HOC.
# Cartble plugin integration checklist before going live
Source: https://help.cartble.com/plugins/plugin-checklist
Before deploying a Cartble plugin, use this checklist to confirm registration, data scoping, UI consistency, and code quality are production-ready.
Before you deploy a custom plugin or submit it for review, work through the items below. This checklist covers every requirement outlined in the Cartble plugin development guide — from registration and data scoping to UI consistency and directory hygiene. A plugin that passes all items here is ready for production.
## Registration and navigation
* [ ] **Plugin registered in the main plugin registry** — your plugin's loader is included in `src/core/plugin-registry.ts` under `PLUGIN_LOADERS` and resolves correctly via `getAllPluginsAsync()` / `getInstalledPluginsAsync()`.
* [ ] **`adminApps` defined with icons and labels** — every page your plugin exposes has an entry in the `adminApps` array with a unique `id`, a human-readable `label`, and a valid Lucide `icon` component. These entries drive the admin sidebar navigation.
## Bridge and context isolation
* [ ] **All exported pages wrapped with `withBridge`** — every component referenced in `adminApps` and `slots` is wrapped with your plugin's Bridge HOC (e.g., `withYourPluginBridge`). This HOC provides an isolated `QueryClient` and any plugin-local context, preventing pollution of the main application's React tree.
## Pricing and currency display
* [ ] **All price displays use `formatPrice`** — every monetary value rendered in your plugin's UI is formatted through `formatPrice` from `useTranslation`. No raw `.toFixed()` calls, no custom currency symbols, and no hardcoded locale assumptions.
## Firestore data access
* [ ] **Direct updates to core `resources` collection follow the platform schema** — if your plugin reads or writes to `platforms/{platformId}/resources/`, every document field conforms to Cartble's existing resource schema. No conflicting or shadow fields are introduced.
* [ ] **All Firestore data stored under `platforms/{platformId}/`** — every collection your plugin reads from or writes to sits under the platform-scoped Firestore path. No data is written at the root level or to a path outside the current platform's namespace.
## State management and cache scoping
* [ ] **React Query keys include `platformId`** — every `useQuery` and `useMutation` call in your plugin uses a query key with `platformId` as the first element (e.g., `[platformId, 'your-plugin', 'resource-type']`). This prevents cache entries from leaking between platforms when a user switches accounts.
## Hardcoding and global constants
* [ ] **No hardcoded platform IDs, collection names, or global constants** — your plugin contains no string literals that represent a specific `platformId`, no hardcoded Firestore collection paths (e.g., `platforms/abc123/...`), and no global variables that would break in a multi-platform deployment. All paths are constructed dynamically using `usePlatform()`.
## UI components and design system
* [ ] **UI components sourced from `src/components/ui/`** — your plugin does not define custom button, input, or confirmation dialog components. All interactive controls use `Button.tsx`, `Input.tsx`, and `ConfirmModal.tsx` from the shared UI library.
* [ ] **Tailwind classes match the admin design system** — your plugin's styling uses the same Tailwind color palette, spacing scale, border radius, and typography conventions as the rest of the admin. No custom CSS, no arbitrary color values, and no overrides to global styles.
## Directory hygiene
* [ ] **Plugin directory is self-contained under `src/plugins/[plugin-name]/`** — all plugin code lives inside your plugin's dedicated subdirectory. Your plugin does not import from another plugin's directory, does not place files outside its scope, and does not modify any file in `src/plugins/core/` or `src/core/`.
***
Use the `smart-price` plugin at `src/plugins/smart-price` as your gold-standard reference when verifying each item on this checklist. It demonstrates every pattern correctly — from the Bridge HOC and scoped React Query keys to the `adminApps` structure and Firestore data conventions.
## Next steps
Step-by-step guide to building a custom Cartble plugin from directory structure to registration.
Deep dive into modularity, Firestore data conventions, React Query patterns, and the UI design system.
# How to build a custom plugin for your Cartble admin
Source: https://help.cartble.com/plugins/plugin-development
Learn how to build a custom Cartble plugin that adds admin pages, sidebar navigation, and scoped Firestore data to your store without touching core code.
Cartble's plugin architecture is designed to let developers extend the admin with new functionality while keeping all custom code self-contained and maintainable. This guide walks you through building a custom plugin from scratch — covering directory structure, the Bridge pattern, plugin registration, platform-aware data access, and state management conventions. The `smart-price` plugin at `src/plugins/smart-price` is the gold-standard reference implementation to study as you work through this guide.
## Who this is for
This guide is written for developers who are comfortable with React, TypeScript, and Firestore. You should have access to the Cartble codebase and be familiar with how the admin shell is structured before building a plugin.
## Plugin directory structure
Every plugin lives in its own subdirectory under `src/plugins/`. All plugin-specific code — pages, hooks, services, types, and components — must be entirely self-contained within that directory. Nothing inside a plugin should import from another plugin's directory.
```
src/plugins/
└── your-plugin-name/
├── index.ts # Plugin definition and registration export
└── src/
├── pages/ # Full-page React components
├── components/ # Shared UI components used within the plugin
├── hooks/ # Custom React hooks
├── services/ # Firestore and API service functions
├── types/ # TypeScript interfaces and types
└── utils/ # Helper utilities
```
## What a plugin can do
A registered plugin can:
* **Add sidebar menu items** — define one or more `adminApps` entries with icons, labels, and page components
* **Add full admin pages** — React components rendered inside the admin shell when a sidebar item is clicked
* **Inject UI slots** — render components in predefined positions like product table columns or checkout flows
* **React to platform hooks** — execute logic when events like `on-checkout-start` or `on-order-placed` fire
* **Read and write Firestore data** — scoped to your platform's collection path
## The Bridge pattern
Plugins should not pollute the main application's React context. Instead, wrap every exported page component with a Higher-Order Component (HOC) that provides the plugin's own React Query client and localized settings. The `smart-price` plugin calls this `withSmartPriceBridge`.
```ts theme={null}
// src/plugins/your-plugin/src/components/YourPluginBridge.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
const queryClient = new QueryClient();
export function withYourPluginBridge(
Component: React.ComponentType
): React.ComponentType
{
return function BridgedComponent(props: P) {
return (
);
};
}
```
Apply `withYourPluginBridge` to every page component you register in `adminApps`. This ensures your plugin's server-state management is completely isolated from the main application.
## Plugin registration
Define and export your plugin as a `Plugin` object in your `index.ts`. The plugin registry reads this object to wire up sidebar navigation, slots, and hooks.
```ts theme={null}
// src/plugins/your-plugin/index.ts
import { Plugin } from '../core/types';
import { LayoutGrid, Settings } from 'lucide-react';
import dynamic from 'next/dynamic';
import { withYourPluginBridge } from './src/components/YourPluginBridge';
const YourPluginDashboard = dynamic(() => import('./src/pages/Dashboard'));
const YourPluginSettings = dynamic(() => import('./src/pages/Settings'));
export const YourPlugin: Plugin = {
id: 'your-plugin',
name: 'Your Plugin',
description: 'A short description of what your plugin does.',
version: '1.0.0',
category: 'other',
isNative: true,
adminApps: [
{
id: 'your-plugin-dashboard',
label: 'Dashboard',
icon: LayoutGrid,
component: withYourPluginBridge(YourPluginDashboard),
},
{
id: 'your-plugin-settings',
label: 'Settings',
icon: Settings,
component: withYourPluginBridge(YourPluginSettings),
},
],
};
export default YourPlugin;
```
After creating this file, register your plugin in the main plugin registry at `src/core/plugin-registry.ts` so it is picked up by the `PluginProvider`.
## Accessing platform context
Never hardcode a `platformId` or build Firestore collection paths by hand. Always use the `usePlatform` hook to retrieve the current platform's ID and scoped settings at runtime.
```ts theme={null}
import { usePlatform } from '@/src/hooks/usePlatform';
export function useYourPluginData() {
const { platformId, settings } = usePlatform();
// Safe — platformId comes from context
const collectionPath = `platforms/${platformId}/your_plugin_data`;
// ...
}
```
Never hardcode a `platformId` string, collection name, or global constant inside your plugin. Doing so will cause data collisions when multiple platforms share the same Cartble deployment. Always use `usePlatform()` to retrieve the scoped ID at runtime.
## Data storage in Firestore
Store all plugin data under the platform-scoped path. Follow these conventions:
| Data type | Firestore path |
| ---------------------------- | ------------------------------------------ |
| Products / primary assets | `platforms/{platformId}/resources/` |
| Orders / transactions / logs | `platforms/{platformId}/records/` |
| Plugin-private data | `platforms/{platformId}/your_plugin_data/` |
Use a descriptive collection name for your plugin's private data (e.g., `smart_price_data`, `your_plugin_data`) to avoid collisions with other plugins.
## State management
Use React Query for all server-side state inside your plugin. Always scope your query keys with `platformId` to prevent data from one platform leaking into another when a user switches accounts.
```ts theme={null}
import { useQuery } from '@tanstack/react-query';
import { usePlatform } from '@/src/hooks/usePlatform';
export function useYourPluginSettings() {
const { platformId } = usePlatform();
return useQuery({
// platformId is always the first element of the key
queryKey: [platformId, 'your-plugin', 'settings'],
queryFn: () => yourPluginService.getSettings(platformId),
});
}
```
## Reference implementation
Study the `smart-price` plugin at `src/plugins/smart-price` for a complete example that demonstrates every pattern described in this guide — the Bridge HOC (`SmartPriceBridge`), full `adminApps` registration, Firestore service abstraction, scoped React Query keys, and UI component reuse from `src/components/ui/`.
Start by copying the directory structure of `src/plugins/smart-price` and replacing the domain logic. This gives you a working scaffold with all the correct wiring already in place.
# SmartPrice AI: automated product pricing for Cartble
Source: https://help.cartble.com/plugins/smart-price-ai
SmartPrice AI analyzes your costs, expenses, and target margin to calculate and apply optimal prices across your entire product catalog automatically.
SmartPrice AI is an analytics plugin built into Cartble that takes the guesswork out of product pricing. Instead of setting prices manually, you define your target profit margin and your cost structure — raw materials, packaging, labor, fixed costs, and transaction fees — and SmartPrice AI calculates the recommended selling price for each product. You can review suggestions individually or apply them in bulk across your catalog.
## Key capabilities
SmartPrice AI gives you a comprehensive set of tools to build and manage your pricing strategy from a single place inside the admin.
Set your desired profit margin percentage. SmartPrice AI uses this as the floor for every price recommendation.
Enter your estimated monthly sales volume so the engine can distribute fixed costs accurately across your products.
Log recurring expenses — rent, staff, packaging — as fixed costs. SmartPrice AI factors these into every price calculation.
Define your payment gateway and marketplace fees so your recommended prices already account for those deductions.
Create and manage promotional discounts from within the plugin without affecting your base pricing configuration.
Review AI-calculated prices per product, adjust individually, and apply changes to your live catalog in one action.
Enable Smart Rounding to automatically round recommended prices to the nearest `.90` psychological price point (e.g., $49.90 instead of $50.12), improving perceived value without manual adjustment.
## How to enable SmartPrice AI
To activate the plugin, navigate to **Admin → Plugins** and click the **SmartPrice AI** card. If your current plan includes the `enableSmartPrice` capability, you will see an **Enable** toggle. Turn it on and SmartPrice AI will appear as a new section in your admin sidebar.
SmartPrice AI is available on specific Cartble plans. If you do not see it in the Plugins Manager or the Enable toggle is unavailable, visit **Admin → Billing** to review your current plan and upgrade if needed.
## Configuration walkthrough
Once SmartPrice AI is enabled, use the following steps to set up your pricing configuration.
After enabling the plugin, a **Smart Price** section appears in your admin sidebar. Click **Home** to see an overview of your current pricing health, then proceed to the individual configuration pages.
Go to **Smart Price → Price Builder** and enter your target margin percentage — for example, `40` for a 40% profit margin. This value is used as the baseline for all price calculations.
Still in Price Builder, enter how many units you expect to sell per month. SmartPrice AI divides your fixed costs by this number to determine the per-unit cost burden, which keeps your per-product prices accurate at scale.
In Price Builder, toggle **Smart Rounding** on if you want recommended prices automatically adjusted to a `.90` psychological price point (for example, $49.90 instead of $50.13). This setting applies to all price recommendations across your catalog.
Navigate to **Smart Price → Fixed Costs** and add your ongoing expenses such as rent, staff wages, and packaging materials. Each expense entry reduces the net margin available per product and is reflected in updated price recommendations.
Go to **Smart Price → Transaction Fees** and enter the fee rates charged by your payment gateway or marketplace. SmartPrice AI deducts these percentages from the final price calculation so your target margin is preserved after fees.
Return to **Smart Price → Price Builder** to see the AI-calculated recommended price for each product based on your full cost structure. Review prices individually, make any adjustments, and click **Apply** to update your live product catalog.
## SmartPrice AI admin pages
The plugin adds the following pages to your admin sidebar under the **Smart Price** section:
| Page | Purpose |
| ------------------ | ----------------------------------------------------------------- |
| Home | Overview dashboard of your pricing health and recent changes |
| Price Builder | Per-product pricing recommendations based on your full cost model |
| Discounts | Create and manage promotional discounts |
| Fixed Costs | Log recurring expenses like rent, staff, and utilities |
| Pricing Categories | Group products into pricing tiers or strategies |
| Transaction Fees | Define payment gateway and marketplace fee rates |
| Packaging | Track packaging material costs per product |
| Marketing Calendar | Schedule pricing changes around promotional events |
Update your Fixed Costs and Transaction Fees regularly — especially after renewing supplier contracts or changing payment providers. Stale expense data leads to underpriced products and eroded margins.
# Quickstart: launch your Cartble store in minutes
Source: https://help.cartble.com/quickstart
Go from zero to a live Cartble storefront in six steps — pick a blueprint, add your first product, connect payments, and publish your store URL.
Getting your first Cartble store live takes less time than you might expect. This guide walks you through every step, from creating your account to sharing a working storefront URL with your first customers. Follow each step in order and you'll have a fully operational store ready to accept orders by the end.
Go to [cartble.com](https://cartble.com) and click **Get started**. Enter your email address and create a password to register your account. Once you confirm your email, Cartble takes you directly into the onboarding flow to set up your first platform.
Cartble asks you to pick the blueprint that best describes your business. Your choice shapes the admin interface, catalog labels, and checkout options for your entire store.
**Retail** is built for merchants selling physical or digital products. Your catalog uses stock levels, SKU search, categories, and collections. The order manager tracks sales and shipments, and the dashboard shows stock-level alerts for items running low or out of stock.
**On-demand** covers food delivery and craft goods that are made to order. After selecting On-demand, Cartble asks whether your store is **Food-based** (restaurants, cafés, ghost kitchens) or **Craft-based** (handmade or custom-produced items). The order manager becomes a Kitchen Display or Workshop Manager with real-time prep tracking.
**Booking** is for time-based businesses. After selecting Booking, Cartble asks whether you offer **Services** (consultations, sessions, appointments) or **Spaces** (rooms, studios, equipment rentals). The order manager becomes a Session Manager or Booking Center, and you can assign staff members to each service.
If you're unsure which blueprint fits, start with the one closest to your main revenue stream. You can review your blueprint configuration later from your platform settings.
Give your store its identity. On the **Identity** step of onboarding, fill in:
* **Platform name** — the name customers see on your storefront.
* **Primary color** — used as the main brand color across your storefront theme.
After your platform is created, go to **Settings > Profile** to add your store description, support email, logo, phone number, and social links for Instagram, TikTok, Facebook, YouTube, and Pinterest.
Navigate to your store's admin dashboard and open the **catalog section** (the label varies by blueprint — it may read *Stock Resources*, *Menu / Dishes*, or *Offered Services*).
Click **New Resource** to open the product editor, then fill in:
* **Name** — the title shown to customers on your storefront.
* **Price** — the selling price in your store's configured currency.
* **Stock** — the quantity available (for Booking blueprints, this sets capacity).
* **Images** — upload one or more photos of your product or service.
* **Category** — assign the resource to at least one category so it appears in your catalog navigation.
Click **Save** when you're done. Cartble automatically sets the resource status to **active**, making it visible on your storefront immediately.
Cartble pre-populates your catalog with three sample resources during onboarding so you can see how the admin interface works before adding your own items. You can edit or delete those samples at any time.
Go to **Settings > Payments** and connect at least one payment method so your store can accept orders.
* **Stripe** — click **Connect Stripe** and follow the OAuth flow to link your Stripe account. Once connected, your storefront accepts card payments at checkout with no transaction fees from Cartble.
* **Manual Payment** — enable this option to accept cash on delivery, bank transfers, or in-person payments. Customers place orders and pay through an agreed offline method.
You can enable both options simultaneously if your customers expect a choice at checkout.
Your storefront will not accept orders until at least one payment method is active. Make sure you complete this step before sharing your store URL.
Your storefront is already live the moment your platform is created. Open a browser and visit:
```
https://yourslug.mycartble.com
```
Replace `yourslug` with the slug you chose during onboarding. You'll see your storefront exactly as customers will — including the sample resources Cartble seeded for you and any products you've added.
Share this URL with your first customers, add it to your social bios, or set up a custom domain from **Settings > Domain** to use your own branded address.
Use your store's password-protection feature during setup if you want to preview everything privately before going public. Go to **Settings > Availability** and switch the mode to **Password Protected**, then share the password only with your team.
## What to do next
Customize your storefront theme, navigation, and pages to match your brand.
Learn how to manage orders, apply discounts, and configure shipping or delivery options.
Connect your own domain so customers reach your store at a branded URL.
Activate SmartPrice AI, Smart Importer, and other built-in plugins to automate key parts of your business.
# Sell digital products with automatic file delivery
Source: https://help.cartble.com/selling/digital-delivery
Automatically deliver secure download links or external URLs to customers the moment payment is confirmed — no manual follow-up required.
When a customer pays for a digital product in your Cartble store, the platform automatically handles delivery for you. As soon as the order's payment is confirmed, Cartble generates a secure download link for each digital item and makes it available in the customer's order detail page — no emails to send, no manual uploads to manage. You control whether to host the file directly in Cartble or link out to an external URL, and you can set download limits and expiration windows on each product.
## How digital delivery works
The moment an order's payment is confirmed, Cartble automatically scans the order's items for any digital products and generates the appropriate link for each one — no action required on your part.
Upload your file directly to Cartble. When the order is paid, Cartble generates a **signed URL** — a time-limited, cryptographically secure link to the file in cloud storage. The link expires after the number of days you configure on the product.
Paste a URL from any external source (Google Drive, Dropbox, a CDN, or your own server). Cartble stores the link and reveals it to the customer only after payment is confirmed — your file stays where it already lives.
## Setting up a digital product
Go to **Admin → Products → New Product**. Fill in the product name, description, price, and images as you would for any product.
In the **Product Type** selector, choose **Digital**. The digital delivery fields will appear below the main product form.
Choose one of the two delivery modes:
* **Upload a file** — drag and drop or browse for the file you want to sell (e.g., a PDF, ZIP archive, audio file, or software binary). Cartble stores it securely and generates signed URLs at purchase time.
* **External link** — paste the full URL of your file hosted elsewhere (e.g., a Google Drive share link or a Dropbox direct download URL). Cartble will surface this URL to the customer after payment.
Enter a number in the **Download Limit** field to cap how many times the link can be accessed (e.g., `3`). Leave blank or set to `0` for unlimited downloads.
Enter the number of days the download link should remain valid in the **Link Expiration (days)** field. For example, `7` means the link expires one week after the order is paid. The default is **7 days**.
Write a short message in the **Delivery Instructions** field. This text is shown to the customer alongside their download link after purchase — use it to explain how to install software, unzip files, or access a course platform.
Set the product status to **Active** and save. Your digital product is now live and ready to sell.
## What the customer sees after purchase
Once an order containing a digital product is paid, Cartble automatically populates a **Downloads** section in the customer's order detail view. For each digital item in the order, the customer sees:
* The **product name**
* A **Download** button or link pointing to the signed URL or external link
* The **expiry date** of the link (for hosted files)
* Any **delivery instructions** you added to the product
The customer does not need to contact you or wait for a follow-up email — access is instant upon payment confirmation.
Signed download links for hosted files expire after the number of days you configured on the product. Once expired, the link stops working and the customer can no longer download the file. Remind customers in your delivery instructions to download their purchase promptly after payment.
## Delivery modes compared
| | Hosted file | External link |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
| **File stored in** | Cartble cloud storage | Your external service |
| **Link type** | Signed URL (time-limited) | Direct external URL |
| **Link expiration** | Configurable per product | Not applicable — link persists as long as the external source does |
| **Download limit** | Configurable per product | Not enforced by Cartble |
| **Best for** | eBooks, software, audio files, templates | Large video files, courses on third-party platforms |
Set your link expiration to at least **7 days** (the default) to give customers a reasonable window to download across different devices and schedules. For evergreen products like software licenses, consider a longer window such as 30 days.
## Managing digital products
You can update the file, expiration settings, or delivery instructions on a digital product at any time from **Admin → Products**. Changes apply to future orders only — links already delivered to existing customers are not affected.
If you delete or move a file that is referenced by an existing signed URL, customers who haven't yet downloaded their purchase will receive an error when they try to access the link. Always replace rather than delete hosted files, or extend link expiration before removing a file.
# Create discounts and coupon codes for your store
Source: https://help.cartble.com/selling/discounts
Build percentage, fixed-amount, and free-shipping promotions using manual coupon codes or automatic cart rules with scopes, limits, and date ranges.
Cartble's discount engine lets you run targeted promotions without a third-party app. You can create coupon codes that customers enter at checkout, or define automatic promotions that apply silently the moment a customer's cart qualifies. Every discount rule is fully configurable — from the type of value it applies, to which products it covers, to how many times it can be used before it expires.
## Discount methods
Every discount rule uses one of two methods to reach the customer's cart.
You generate a code (e.g., `VIP20` or `SUMMER50`) and share it with customers. The discount is applied only when the customer enters the code at checkout.
No code required. Cartble evaluates the rule against the cart automatically — if the cart meets all conditions, the discount is applied instantly without any customer action.
## Discount types
| Type | How it works | Example |
| ----------------- | --------------------------------------------------------- | --------------------------------- |
| **Percentage** | Reduces the eligible subtotal by a percentage. | 20% off all products |
| **Fixed Amount** | Deducts a flat monetary value from the eligible subtotal. | $10 off orders over $50 |
| **Free Shipping** | Waives the shipping fee when conditions are met. | Free shipping on orders over \$75 |
## Application scope
When you create a discount, you choose which products it applies to.
The discount applies to every item in your store. This is the broadest scope and is ideal for sitewide sales or welcome promotions.
Limit the discount to a specific product category type. Available blueprint types are:
* **Physical Products** — retail goods
* **Digital Products** — downloadable files or links
* **Services & Bookings** — appointment-based offerings
* **Subscription Clubs** — recurring subscription products
Use this scope when running a promotion that should apply only to one vertical, such as "20% off all subscriptions."
Hand-pick exactly which products are eligible. Select individual product IDs from your catalog. This is the most targeted scope and prevents the discount from being used on anything outside your selection.
## Conditions and prerequisites
Add minimum thresholds to ensure a discount is only applied when the cart meets a baseline requirement.
| Condition | Description |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| **Minimum cart subtotal** | The cart must reach a set monetary value before the discount activates (e.g., \$50 minimum). |
| **Minimum item quantity** | The cart must contain at least a specified number of eligible items. |
You can combine both conditions on a single rule — for example, require at least 3 items **and** a \$30 subtotal.
## Usage limits
Control how many times a discount can be redeemed to protect your margins.
Set a maximum number of times the discount can be used across all customers combined (e.g., 100 total uses). Set to `0` for unlimited uses.
Toggle **Yes (1 per Email)** to ensure each customer email address can only redeem the discount once, regardless of how many orders they place.
## Date range
Every discount can have a **start date** and an optional **end date**.
* The discount becomes active at the start date and time you configure.
* If you set an end date, the discount automatically deactivates after that date — no manual intervention required.
* Leave the end date blank to keep the discount active indefinitely (subject to usage limits).
## Active / Inactive toggle
Use the **Active in Store** / **Paused / Inactive** toggle to enable or disable a discount rule at any time, regardless of its date range or usage count. This is useful for quickly pausing a promotion during an incident or staging a rule before its start date.
## Creating a new discount
From your admin dashboard, navigate to **Discounts** in the left sidebar.
Click the **New Discount** button in the top-right corner of the Discounts page.
Select **Manual Coupon** if you want customers to enter a code, or **Automatic** if the discount should apply without a code. If you choose Manual Coupon, enter a code in the **Coupon Code** field or click **Generate random code** to have Cartble create one for you.
Choose **Percentage (%)**, **Fixed Amount (\$)**, or **Free Shipping** from the Discount Type selector. For percentage and fixed-amount types, enter the discount value in the corresponding field.
Select the application scope (all products, by product type, or specific products). Optionally set a minimum subtotal or minimum quantity under **Minimum Prerequisites**.
Set a global usage limit and toggle per-customer restrictions if needed. Enter the start date and, optionally, an end date.
Choose **Active in Store** to make the discount live immediately, or **Paused / Inactive** to save it without activating. Click **Create Discount** to save the rule.
Give each discount an **Internal Title** that clearly describes its purpose (e.g., "Black Friday 20% OFF" or "Free Shipping South"). This title is only visible to you in the admin dashboard — customers only see the code or the discount line on their cart.
## Discount status labels
After creation, each discount in your list displays a status badge:
| Badge | Meaning |
| ------------- | ----------------------------------------------------- |
| **Active** | The rule is live and currently accepting redemptions. |
| **Paused** | The rule exists but has been manually disabled. |
| **Expired** | The end date has passed. |
| **Exhausted** | The global usage limit has been reached. |
# Manage and fulfill orders from your dashboard
Source: https://help.cartble.com/selling/orders
Track every order from placement to fulfillment, manage statuses, handle refunds, and run a real-time Kitchen Display System for food businesses.
Every sale your store generates lands in the Orders section of your admin dashboard. From here you can view order details, update fulfillment status, process refunds, and — if you run a food or on-demand business — push tickets straight to a Kitchen Display System (KDS) for your kitchen staff. Whether you sell physical goods, digital downloads, services, or meals, orders follow a consistent lifecycle that keeps you in control at every step.
## How orders flow
When a customer completes checkout, Cartble immediately creates an order record in your dashboard. The order captures the customer's details, the items purchased, the delivery type chosen, any discounts applied, and the payment outcome. Your job from that point is to move the order through its fulfillment stages until it reaches the customer.
```
Customer checks out → Order created (pending) → Payment confirmed (paid) → You fulfill → Completed
```
## Order statuses
Cartble tracks two independent status dimensions for every order: **financial status** and **fulfillment status**.
### Financial status
| Status | What it means |
| ---------------- | ------------------------------------------------------------------- |
| `pending` | Payment has not yet been confirmed (e.g., awaiting bank transfer). |
| `paid` | Payment was successfully captured. |
| `partially_paid` | A partial payment was received; the remainder is still outstanding. |
| `refunded` | The full order amount has been returned to the customer. |
| `voided` | The order was cancelled before payment was captured. |
### Fulfillment status
| Status | What it means |
| --------------------- | --------------------------------------------------------- |
| `unfulfilled` | No items have been shipped or handed off yet. |
| `partially_fulfilled` | Some items have been fulfilled; others are still pending. |
| `fulfilled` | All items have been delivered or handed off. |
| `restocked` | Items were returned and inventory was added back. |
Legacy orders may also carry a single combined `status` field with values such as `pending`, `processing`, `shipped`, `delivered`, or `cancelled`. New orders use the split financial/fulfillment model above.
## Managing orders in the dashboard
Navigate to **Admin → Orders** to see your full order list.
Use the status filter tabs at the top of the list to narrow orders down by financial or fulfillment status — for example, quickly surfacing all `paid` + `unfulfilled` orders that are ready to ship.
Type into the search bar to find a specific order by transaction number (e.g., `#1001`) or by customer name or email address.
Click any order to open its detail view. You'll see the full item breakdown, applied discounts, shipping address, and current status — plus quick action buttons.
Mark an order as fulfilled directly from its detail page once you've dispatched the goods or completed the service.
## Delivery types
Every order records the delivery method the customer selected at checkout. Cartble supports three delivery types out of the box:
The customer provided a shipping address and expects the order to be delivered to their location. The order detail view displays the full shipping address.
The customer will collect the order from your physical location. No shipping address is required. Use this for in-store pickup or curbside collection.
The customer is ordering from a table in your venue (common in restaurants). The table identifier is stored in the order metadata.
You can control which delivery types appear at checkout under **Settings → Checkout → Enabled Delivery Types**. Disable any types that don't apply to your business.
## Kitchen Display System (KDS)
If you operate a food, café, or on-demand delivery business, the Kitchen Display System gives your kitchen staff a real-time, auto-refreshing view of incoming orders — no paper tickets required.
Go to **Admin → Kitchen Orders** in your dashboard. The KDS panel opens and immediately begins listening for new orders in real time.
Orders flow across three columns as your team works through them:
* **Queued** — new orders waiting to be started.
* **In Preparation** — orders actively being prepared in the kitchen.
* **Ready** — orders finished and waiting for pickup or dispatch.
Each order card shows the transaction number, customer name, delivery type (`delivery`, `pickup`, or `table`), item list with any modifiers selected, and the time elapsed since the order was placed.
Tap individual items on a card to mark them as done as your team prepares them. When you are ready to move the order to the next stage, press the **Advance** button at the bottom of the card — this moves the order from Queued → In Preparation → Ready in sequence.
Click the fullscreen toggle in the top-right corner of the KDS to expand it to your full screen — ideal for a dedicated kitchen tablet or monitor.
The KDS also supports scheduled orders. Orders that the customer placed in advance show a calendar badge with the scheduled date and time slot so your team can prepare them at the right moment.
### KDS audio alerts
The KDS plays a kitchen bell chime whenever a new order arrives, so staff are immediately notified even when they aren't looking at the screen. Use the sound toggle at the top of the KDS panel to mute or unmute alerts.
## Booking and appointment orders
If your store uses the **Bookings** blueprint (services, appointments, classes), orders also carry scheduling metadata — including the session duration, assigned staff member, and booked time slot. You can view upcoming appointments directly from the order detail page.
Sort your orders by scheduled date to see a chronological view of upcoming sessions and prepare your team's schedule in advance.
## Refunds and order actions
From any order's detail page you can:
* **Refund** the order — this updates the financial status to `refunded` and records the refund amount.
* **Cancel** the order — this voids the transaction and, if inventory tracking is enabled, returns stock to your catalog.
* **Restock items** — mark items as restocked when a returned order's goods are added back to your available inventory.
Refunds processed through Cartble update the order record, but the actual funds transfer depends on your payment provider. For Stripe payments, the refund is also submitted to Stripe automatically. For manual payments (e.g., bank transfer), you must return the funds to the customer directly.
# Accept payments with Stripe on your Cartble store
Source: https://help.cartble.com/selling/payments
Connect Stripe for online card payments or enable manual payments for bank transfer and cash — all with zero transaction fees from Cartble.
Cartble supports two payment methods out of the box: **Stripe** for online card payments (credit cards, debit cards, Apple Pay, and Google Pay), and **Manual** for offline scenarios like bank transfer or cash on delivery. You can enable both simultaneously and let the customer choose at checkout. Cartble never adds its own transaction fees on top of your payment provider's standard rates.
## Payment methods at a glance
Accept online payments worldwide. Customers pay with credit or debit cards, Apple Pay, or Google Pay directly on your checkout page. Funds settle into your Stripe account on your normal payout schedule.
Display custom payment instructions to customers at checkout (e.g., bank account details or cash-on-delivery instructions). You confirm the payment manually once funds are received.
## Connecting Stripe
In your admin dashboard, go to **Settings → Payments** (or navigate to **Plugins → Stripe Payments**). You'll see the Stripe Payments configuration panel.
Toggle **Stripe Payments** to the enabled position at the top of the panel.
Paste your **Publishable Key** (starts with `pk_live_` or `pk_test_`) and your **Secret Key** (starts with `sk_live_` or `sk_test_`) from your [Stripe Dashboard → Developers → API keys](https://dashboard.stripe.com/apikeys).
In your Stripe Dashboard, go to **Developers → Webhooks → Add endpoint**. Set the endpoint URL to your Cartble webhook URL (shown in the Stripe settings panel). Select the events listed in the [Webhook events](#webhook-events) section below, then save the endpoint. Stripe will display a **Signing Secret** (starts with `whsec_`) — keep this available for your server-side configuration, as it allows Cartble to verify that incoming webhook calls genuinely originate from Stripe.
Keep **Test Mode** toggled on and use a [Stripe test card](https://stripe.com/docs/testing#cards) (e.g., `4242 4242 4242 4242`) to place a test order. Verify the order appears in your dashboard with a `paid` financial status before switching to live mode.
Never share or expose your Stripe **Secret Key** publicly — not in client-side code, public repositories, or support tickets. The secret key grants full access to your Stripe account. If you suspect it has been compromised, roll it immediately from your Stripe Dashboard.
### Test mode
The Stripe settings panel includes a **Test Mode** toggle. While test mode is active, transactions are processed against Stripe's test environment and no real money moves. Disable test mode only after you have verified your integration end-to-end with a test card.
## Webhook events
Cartble listens for the following Stripe webhook events to keep your orders and subscriptions in sync:
| Stripe event | What Cartble does |
| ------------------------------- | ------------------------------------------------------------------------------------------------- |
| `checkout.session.completed` | Registers a completed checkout session and creates the associated subscription record in Cartble. |
| `invoice.paid` | Records a successful subscription or invoice payment against the customer's account. |
| `invoice.payment_failed` | Marks the related subscription payment as failed so you can follow up with the customer. |
| `customer.subscription.created` | Creates a new active subscription record in Cartble. |
| `customer.subscription.updated` | Syncs subscription status, current period end, and plan changes. |
| `customer.subscription.deleted` | Marks the subscription as cancelled in Cartble. |
Make sure all six event types above are selected when you configure your Stripe webhook endpoint. Missing events can cause payment records or subscriptions to fall out of sync with your Cartble dashboard.
## Manual payments
Manual payments are ideal when customers pay offline — for example, by direct bank transfer, cash on delivery, or in-person at pickup.
Go to **Settings → Payments** and enable the **Manual Payment** option.
Enter the instructions customers will see at checkout — for example, your bank name, account number, and reference format. Be specific so customers know exactly how to complete the transfer.
When a customer chooses manual payment and places an order, the order is created with a `pending` financial status. Once you confirm receipt of funds, open the order in your dashboard and update the financial status to `paid`.
## Viewing payment records
Navigate to **Admin → Payments** to see a full transaction history across all payment methods.
Each record shows:
* **Transaction number** — matches the order number for easy cross-referencing.
* **Amount** — total charged including tax and shipping.
* **Financial status** — `paid`, `pending`, `refunded`, `partially_paid`, or `voided`.
* **Date** — timestamp of the transaction.
* **Payment method** — Stripe or Manual.
Use the status filter at the top of the Payments view to surface all `pending` manual payment orders at once, making it easy to reconcile your bank statement against outstanding orders each day.
## Currencies
Your store's currency is set in **Settings → Regional**. All prices, discounts, and transaction records are stored and displayed in the currency you configure there. Stripe supports multi-currency payouts — ensure your Stripe account is enabled for any currencies you plan to accept.
# Manage your Cartble plan, subscription, and billing
Source: https://help.cartble.com/settings/billing
Choose a plan, review your invoice history, manage your Stripe subscription, and understand the plan limits that apply to your store.
Cartble's billing system handles your subscription, plan changes, and payment history in one place. You can access it from **Admin → Billing**. Cartble charges zero transaction fees regardless of your plan — the only cost is your monthly or annual subscription. Payments are processed securely through Stripe.
If Cartble offers a free trial period, your plan status shows as **Trialing** and the number of days remaining is displayed on the Billing page. Connect your payment method before the trial ends to avoid any service interruption — your features stay active for the full trial length.
## Subscription status
Your subscription can be in one of four states:
| Status | What it means |
| ------------ | --------------------------------------------------------------------------------------------------- |
| **Active** | Your subscription is current and all plan features are fully unlocked. |
| **Trialing** | You are in a free trial period. Features are available; no charge yet. |
| **Past Due** | A payment attempt failed. Features may be restricted until payment is resolved. |
| **Canceled** | Your subscription has been canceled. Access continues until the end of your current billing period. |
If your status is **Past Due**, update your payment method as soon as possible to restore full access. Go to **Admin → Billing → Manage Billing** and update your card through the Stripe customer portal.
## Plan limits
Every Cartble plan defines a set of limits that govern what your store can do. The following limits apply depending on your plan:
* **Max Resources** (`maxResources`) — the maximum number of products or catalog items you can create. `null` means unlimited.
* **Max Blueprints** (`maxBlueprints`) — the number of store blueprints (commerce types) you can activate. `null` means unlimited.
* **Max Storage** (`maxStorageGb`) — total file storage available for images and digital assets, in gigabytes.
* **Monthly Sales Limit** (`monthlySalesLimit`) — a cap on total order value processed per month, in your store's currency. Plans with `null` have no cap.
* **Overage Fee** (`overageFeePercent`) — if your store exceeds its monthly sales limit, an additional percentage fee applies to the excess. Check your plan details to see the rate for your tier.
* **Stripe Payments** (`enableStripePayment`) — whether your plan allows connecting Stripe to accept card payments.
* **Manual Payments** (`enableManualPayment`) — whether your plan allows manual payment methods (bank transfer, cash on delivery, etc.).
* **Smart Pricing** (`enableSmartPrice`) — access to dynamic or intelligent pricing features.
* **Custom Domain** (`customDomain`) — whether your plan includes the ability to connect a custom domain.
* **Max Staff Members** (`maxStaffMembers`) — the number of team members you can invite to your admin panel.
## Upgrading your plan
Go to **Admin → Billing**.
Browse the available plans and compare their features and limits. Click **Subscribe** or **Upgrade** on the plan you want.
You are redirected to a Stripe-hosted checkout page. Enter your payment details and confirm. Cartble creates a Stripe Checkout Session and redirects you on success.
Your new plan features are unlocked immediately after payment is confirmed. No restart or manual activation is required.
When you upgrade, your new plan limits take effect right away. If you were previously blocked from adding more products, staff, or blueprints, those restrictions are lifted the moment your upgrade completes.
## Managing your billing details
If you need to update your credit card, download invoices, or change your billing information, click **Manage Billing** on the Billing page. This opens the Stripe customer portal, where you can make changes directly to your subscription and payment methods.
## Viewing invoice history
Your transaction history shows every charge processed against your account. Each entry includes:
* **Amount** — total charged, in your billing currency
* **Date** — the date the transaction was created
* **Status** — `paid`, `pending`, or `failed`
* **Invoice ID** — the external reference you can use to cross-reference with Stripe
## Canceling your subscription
To cancel, open the Stripe customer portal via **Manage Billing** and select the cancellation option. By default, Cartble schedules cancellation at the end of your current billing period — your store stays online and fully functional until your paid period runs out. You will not be charged again after cancellation.
# Configure your store's regional and checkout settings
Source: https://help.cartble.com/settings/platform-settings
Control your store's profile, regional preferences, checkout behavior, security modes, and feature flags from a single settings panel.
Platform Settings is the central place to define how your store looks, behaves, and operates. Settings are organized into dedicated sections — Profile, Domains, Regional, Checkout, Security, Features, and Analytics — so you can find exactly what you need without scrolling through unrelated options. Navigate between sections using the sidebar or by appending `?section=profile` (or any section name) to the settings URL.
## Profile
Your profile section controls the public-facing identity of your store and the contact details customers see during checkout and support interactions.
Set your store's display name and a short description that appears on your storefront and in search results.
Add a support email address and phone number customers can use to reach you.
Upload your store logo. It appears in the storefront header, emails, and receipts.
Enter your physical or business address. This is used for tax calculations and shown on invoices.
**Social links** — connect your brand's social media accounts so customers can follow you. Cartble supports links for Instagram, TikTok, Facebook, YouTube, and Pinterest.
## Regional
Regional settings control the locale experience for your customers and the format of dates, prices, and measurements throughout your store.
| Setting | Options |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| **Timezone** | UTC, America/Sao\_Paulo, America/New\_York, America/Los\_Angeles, Europe/London, Europe/Paris, Asia/Tokyo |
| **Currency** | Configurable currency code (e.g. USD, BRL, EUR) |
| **Language** | Store display language |
| **Measurement system** | `metric` or `imperial` |
## Checkout
Checkout settings determine what delivery and fulfillment methods customers can choose during the buying process.
Toggle which fulfillment methods appear at checkout:
* **Delivery** — ship or courier the order to the customer's address
* **Pickup** — customer collects the order from your location
* **Table** — customer places an order for dine-in or table service (food & beverage stores)
You can enable any combination of the three. At least one must be active.
When enabled, customers must create an account or log in before they can complete a purchase. This is useful for stores that want to track customer order history or restrict access to registered buyers.
## Security & Availability
Control who can access your storefront and what they see when your store is not fully open.
Your store is publicly accessible to all visitors. This is the default mode.
Visitors see a password prompt before they can browse your store. Set a storefront password and share it with trusted customers — useful for pre-launch previews or wholesale-only stores.
Display a banner message to visitors letting them know your store is temporarily unavailable. You can set an optional **expected return date** so customers know when to come back.
Restricts purchasing outside of your configured operating hours. Browsing may still be allowed depending on your `allow_browsing_without_buying` setting.
Puts your storefront into a full maintenance state. Visitors see a maintenance notice and cannot browse or purchase.
## Features
Feature flags activate blueprint-specific capabilities for your store. These toggles unlock behaviors tailored to particular commerce models.
| Feature | What it enables |
| ------------------- | ----------------------------------------------------------------------------- |
| `preparable` | Orders go through a preparation queue before fulfillment (food and on-demand) |
| `customizable` | Customers can add special instructions or customizations to items |
| `schedulable` | Items or services can be booked for a future date and time |
| `variant_heavy` | Optimized catalog handling for products with many variants |
| `staff_managed` | Services and appointments are assigned to specific staff members |
| `digital_resources` | Support for downloadable or digital products |
| `subscriptions` | Enables recurring subscription purchases |
Some features are plan-gated. If a feature toggle is locked, you need to upgrade your Cartble plan to unlock it. Head to **Admin → Billing** to see which plan includes the capability you need.
# Invite team members and manage staff roles and access
Source: https://help.cartble.com/settings/team
Add staff and collaborators to your Cartble store, control their roles, and manage service providers for booking and scheduling businesses.
Cartble lets you bring your team into the admin panel so you're not managing your store alone. Whether you run a restaurant, a boutique, or a service business, you can invite colleagues to help with orders, inventory, bookings, and more. Each person you add gets their own login and is assigned a role that defines what they can access.
## Roles
Cartble uses two primary access levels:
Full access to every part of the admin panel, including billing, settings, and team management. Only the store owner holds this role, and it cannot be transferred through the UI.
Access to day-to-day operations such as orders, products, and customers. Members cannot access billing or make platform-wide configuration changes unless granted additional permissions.
## Inviting a team member
In your Cartble admin, go to **Settings → Team**.
Click **Invite Member** to open the invitation form.
Type the email address of the person you want to add. Make sure it matches the address they will use to log in to Cartble.
Click **Send Invite**. Cartble sends an email invitation to that address. The invitation appears in your admin panel with a **Pending** status until they accept.
Once the invited person accepts and creates their account, they appear in your team member list with an **Active** status and can log in to your admin panel.
## Staff members for booking and service businesses
If your store uses the `staff_managed` feature (enabled in **Settings → Platform Settings → Features**), team members can be set up as service providers. This lets you assign specific services or time slots to individual staff so customers book appointments with a particular person.
Staff assignment for bookings and scheduling works alongside the general team system. A person needs to be an active team member before they can be added as a service provider.
## Plan limits
The number of team members you can add depends on your current Cartble plan. Each plan defines a `maxStaffMembers` limit. When you reach that limit, the **Invite Member** button is disabled until you upgrade.
Check your current limit and usage in **Admin → Billing → Plan Details**.
Removing a team member immediately revokes their access to your admin panel. Any pending work they have open is not automatically reassigned. Make sure to hand off any active tasks before removing someone from your team.
# Cartble store blueprints: choose your business model
Source: https://help.cartble.com/store/blueprints
Blueprints are pre-configured industry templates that shape your admin labels, feature set, and storefront behavior to match your business model.
When you create a store on Cartble, you choose a **blueprint** — a pre-configured industry template that tailors every part of your admin experience to match your business. A blueprint determines how your catalog is labeled (products vs. dishes vs. services), which operational features are enabled (stock management, prep times, appointment scheduling), and how your storefront behaves at checkout. You can run multiple blueprints across separate stores, but each store operates under a single blueprint at a time.
## Available blueprints
The **Retail** blueprint is designed for merchants selling physical goods. It activates SKU tracking, stock-level management, shipping and logistics fields, and a Sales Dashboard for managing orders through packing and fulfillment.
**What's included:**
* Stock resources catalog with SKU and stock-level tracking
* Retail price and cost-per-item fields
* Logistics & Shipping panel (dimensions, weight, NCM)
* Sales Dashboard with a **Packing** order stage
* Category and Collection taxonomy for browsing and filtering
* Low-stock and out-of-stock dashboard indicators
**Best for:** clothing, electronics, home goods, specialty retail, and any store shipping physical items to customers.
The **On-demand** blueprint is built for delivery and pickup businesses. It surfaces prep-time configuration, a Kitchen Display System (KDS), and an Order Center that tracks incoming delivery and pickup orders in real time.
**What's included:**
* Resource Catalog with delivery/pickup order management
* On-Demand Parameters for prep time per item
* Order Center with a **Preparing** order stage
* Kitchen Display System for real-time kitchen order management
* Section and Grouping taxonomy (instead of Categories and Collections)
* Out-of-stock and low-stock indicators on the dashboard
**Sub-types:**
The **Food** sub-type refines the On-demand blueprint for restaurants, cafés, ghost kitchens, and food-delivery businesses. It replaces generic labels with food-specific language throughout the admin.
| Feature | Food label |
| ------------ | ----------------------------- |
| Catalog | Menu / Dishes |
| Taxonomy | Menu Categories / Menu Tags |
| Collections | Highlights / Highlight Groups |
| Orders | Kitchen Orders |
| Order center | Kitchen Display |
| Order stage | In Kitchen |
| Add item | New Dish |
Dishes also support modifier groups (e.g., "Extra toppings", "Sauce choice") and kitchen parameters such as per-item prep time.
The **Craft** sub-type adapts the On-demand blueprint for artisan makers and small-batch producers — jewelers, candle makers, custom print shops, and similar businesses.
| Feature | Craft label |
| ------------ | ----------------- |
| Catalog | Handmade Items |
| Collections | Lines & Series |
| Orders | Production Orders |
| Order center | Workshop Manager |
| Order stage | In Production |
| Add item | New Creation |
Production specs replace standard logistics fields, letting you capture materials, production time, and unit readiness instead of shipping weight.
The **Booking** blueprint is designed for service businesses that take appointments or space reservations. It enables duration, staff assignment, buffer time, and an Agenda Manager that tracks upcoming sessions and availability.
**What's included:**
* Offered Services catalog with capacity tracking
* Service Duration and buffer time configuration
* Staff / Professional Assignment per service
* Agenda Manager with an **In Progress** order stage
* Specialty and Service Package taxonomy
* Fully Booked and Limited Availability dashboard indicators
**Sub-types:**
The **Service** sub-type targets appointment-based businesses: salons, clinics, tutors, fitness coaches, and consultants.
| Feature | Service label |
| ------------ | ---------------- |
| Catalog | Services / Plans |
| Orders | Sessions |
| Order center | Session Manager |
| Order stage | In Progress |
| Add item | New Session |
Each service entry supports session parameters such as duration, assigned staff members, and buffer time between appointments.
The **Space** sub-type is designed for venues, co-working spaces, recording studios, and any business renting physical spaces by the hour or day.
| Feature | Space label |
| ------------ | ------------------ |
| Catalog | Spaces and Rooms |
| Collections | Areas & Sectors |
| Orders | Space Reservations |
| Order center | Booking Center |
| Add item | New Space |
| Price | Rental Value |
Space entries include reservation terms and room/resource assignment, so you can track which room or asset is booked for each slot.
## Switching your blueprint
Your blueprint is selected during store setup and shapes your entire admin experience. If your business model evolves and you need to change your blueprint, reach out to Cartble support — the team can assist with the transition and advise on any impact to your existing catalog and order data.
Blueprint changes affect how your catalog labels, order management, and storefront features appear. Contact support before switching to understand the impact on your existing data.
# Organize your catalog with collections and categories
Source: https://help.cartble.com/store/collections
Use collections for curated or rule-based product groups and categories for hierarchical taxonomy to power navigation, filtering, and discovery.
Cartble gives you two complementary tools for organizing your catalog: **collections** and **categories**. They serve different purposes and work best together. Collections are curated or automatically populated groups — think "Summer Sale" or "Best Sellers." Categories are a hierarchical taxonomy that classifies every product in your store, drives navigation filters, and powers on-site search. Understanding the difference helps you build a storefront that's both easy to browse and easy to manage.
## Collections
A collection is a named group of resources. You can build it manually by hand-picking items, or automatically by defining rules that Cartble evaluates to populate the group for you.
### Manual collections
A manual collection gives you direct control over which resources appear in the group. You add and remove items one at a time, making manual collections ideal for editorial curation — seasonal picks, staff favorites, promotional bundles, or any group where the selection logic is too nuanced for rules.
**To create a manual collection:**
1. Go to **Catalog → Collections** and click **New Collection**.
2. Set the **type** to `Manual`.
3. Enter a name, optional description, and cover image.
4. Use the resource picker to add specific items to the collection.
5. Toggle **Show in menu** if you want the collection to appear as a navigation link.
6. Save the collection.
### Automated collections
An automated collection uses rules to determine which resources belong to it. Whenever you add or update a resource, Cartble re-evaluates the rules and updates the collection membership automatically — no manual curation needed.
Each rule has three parts:
| Field | Description |
| ------------- | -------------------------------------------------------------------- |
| **Column** | The resource attribute to evaluate (e.g., `tags`, `vendor`, `price`) |
| **Relation** | The comparison operator (e.g., `equals`, `contains`, `greater_than`) |
| **Condition** | The value to compare against |
You can combine multiple rules — for example, all resources tagged `"organic"` with a price less than `50` — to build precise dynamic groups.
Automated collections stay up to date without any manual work. When you publish a new resource that matches the rules, it appears in the collection immediately.
### Collection settings
Both collection types share these additional settings:
| Setting | Description |
| ----------------------------------- | ----------------------------------------------------------------------------- |
| **Featured** | Marks the collection as a featured group, eligible for homepage placement |
| **Show in menu** | Makes the collection available as a navigation link in the Navigation editor |
| **SEO title** | Custom meta title for the collection page |
| **SEO description** | Custom meta description for the collection page |
| **Template suffix** | Override which storefront template renders this collection's page |
| **Forced resource template suffix** | Override the product template for all resources viewed within this collection |
## Categories
Categories provide a hierarchical taxonomy for your entire catalog. Unlike collections, categories are not curated — they classify every resource into a logical tree that reflects how you think about your inventory.
### Hierarchy and parent/child relationships
Categories support unlimited nesting through parent/child relationships. A `level` field tracks depth, and each category stores its full ancestry in a `path` array — enabling breadcrumb navigation and nested filtering on the storefront.
**Example hierarchy:**
```
Clothing (level 0, parent)
├── Men's (level 1)
│ ├── Shirts (level 2)
│ └── Trousers (level 2)
└── Women's (level 1)
└── Dresses (level 2)
```
**To create a category:**
1. Go to **Catalog → Categories** and click **New Category**.
2. Enter a name and optional description and image.
3. Set a **parent category** if this is a sub-category.
4. Choose a status: `active` (visible) or `hidden` (invisible in navigation and search).
5. Save the category, then assign resources to it from each resource's edit form.
### Category SEO fields
Each category has its own **meta title** and **meta description** fields. These appear in search engine results when a category page is indexed, so writing them clearly improves click-through rates from organic search.
## Showing collections and categories in your storefront
In the Navigation editor, add a collection or category as a menu item by setting the item type to `collection` or `category`. Nested items create dropdown and mega-menu structures.
The Spark theme's **Featured Collection** section displays a collection's resources on your homepage. Set a collection as Featured and select it in the section settings.
Use **categories** for your primary site navigation and filtering sidebar. Use **collections** for promotional groupings and homepage feature sections — they're easier to curate without disturbing your taxonomy.
# Build and customize your storefront navigation menu
Source: https://help.cartble.com/store/navigation
Create and manage navigation menus with links to collections, categories, pages, and custom URLs — including dropdowns and mega-menus.
Your storefront navigation is made up of one or more named **menus**, each containing an ordered list of links. Cartble's Navigation editor lets you add, reorder, nest, and configure every item visually — no code required. The menus you build here are referenced by your theme, so changes appear live on your storefront after publishing.
## Navigation menus
A **NavigationMenu** has a human-readable name and a unique **handle** — a short identifier your theme uses to pull in the right menu. Common handles include `main-menu` (rendered in the header) and `footer` (rendered in the footer). You can create additional menus for secondary navigation bars, landing pages, or any other use case your theme supports.
**To create a new menu:**
1. Go to **Online Store → Navigation** in your admin.
2. Click **Add Menu** and enter a name.
3. Cartble generates a handle from the name automatically (e.g., "Main Menu" → `main-menu`). You can edit the handle if needed.
4. Add items to the menu and save.
## Navigation item types
Each item in a menu points to a destination. You set the **type** when adding or editing an item:
| Type | Destination |
| ------------ | ----------------------------------------- |
| `home` | Links to your storefront homepage |
| `collection` | Links to a specific collection page |
| `category` | Links to a specific category page |
| `page` | Links to a CMS page (About Us, FAQ, etc.) |
| `custom` | Links to any URL you specify manually |
For `collection`, `category`, and `page` items, select the target from a list of your existing content. For `custom` items, enter the full URL in the **URL** field.
## Nested items and dropdown menus
You can nest items under any top-level navigation item to create multi-level menus. Nested items appear as children when a visitor hovers over or taps the parent.
**To add a nested item:**
1. Open an existing menu in the Navigation editor.
2. Click the **Add child** button below any top-level item.
3. Configure the child item's label, type, and target.
4. Drag items using the grip handle to reorder within the same level.
Nesting depth is flexible — you can create sub-children under children for complex structures. Most themes render up to two levels deep in dropdowns and three or more in mega-menus.
## Design options per item
Each navigation item has an optional **design** configuration that controls how it renders when expanded:
| Option | Description |
| ----------------- | ----------------------------------------------------------------------- |
| `displayType` | `dropdown` for a standard flyout, or `mega-menu` for a full-width panel |
| `columns` | Number of columns to use in a mega-menu layout |
| `backgroundImage` | URL of an image to render in the mega-menu background |
| `isFeatured` | Highlights this item visually, often with a badge or accent color |
Design options are rendered by your active theme. The Spark theme supports both `dropdown` and `mega-menu` display types. Check your theme documentation to confirm which options are active.
## Managing items in the Navigation editor
The Navigation editor shows your menu as a drag-and-drop list. You can:
* **Add an item** — click **Add item**, choose the type, set the label and target, and save.
* **Reorder items** — drag the grip handle to move an item up, down, or under another item.
* **Edit an item** — click the edit icon to update the label, target, or design settings.
* **Delete an item** — click the trash icon to remove an item and all its children.
Changes are saved to the menu record when you click **Save Menu**. Your storefront reflects the new structure immediately after saving.
Link your most important collections directly to the `main-menu` for maximum discoverability. Customers who can find a collection from the header are significantly more likely to browse and convert than those who rely on search alone.
Deleting a top-level navigation item also deletes all of its nested children. Restructure your menu before removing parent items to avoid accidentally losing nested links.
# Create custom pages and blog posts for your storefront
Source: https://help.cartble.com/store/pages-blog
Build static pages like About Us or FAQs and publish blog posts with a rich editor, SEO fields, draft/published states, and visibility controls.
Beyond your product catalog, Cartble gives you two content tools for building out your storefront: **CMS Pages** for static informational content and a **Blog** for ongoing publishing. Both are managed from the admin, support draft and published states, and include SEO fields so search engines can index and rank your content correctly.
## Static pages
A **CMS page** is a standalone page with its own URL, content, and SEO settings. Use pages for content that doesn't change often — your About Us story, Contact details, FAQ, shipping and return policies, or any custom landing page.
### Creating a page
1. Go to **Online Store → Pages** in your admin.
2. Click **New Page** and enter a **title**. Cartble generates a URL slug from the title automatically.
3. Write your content in the rich text editor (see [Rich text editor](#rich-text-editor) below).
4. Fill in the **SEO** fields — meta title and meta description.
5. Set the **status** and **visibility**, then save.
### Page status
| Status | Behavior |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| **Draft** | Page exists in your admin but is not accessible on the storefront. Use this while writing or reviewing content. |
| **Published** | Page is live and accessible to visitors at its slug URL. |
### Page visibility
| Visibility | Behavior |
| ----------- | ----------------------------------------------------------------------- |
| **Public** | Any visitor can access the page, whether or not they are logged in. |
| **Private** | Only logged-in customers with the appropriate access can view the page. |
System policy pages (such as Privacy Policy and Terms of Service) are locked to `published` and `public` once created. You can edit their content, but you cannot hide or unpublish them.
## Rich text editor
Both pages and blog posts use a built-in rich text editor that supports full-featured content formatting without writing any HTML.
**Supported formatting and embeds:**
Headings (H1–H6), bold, italic, underline, strikethrough, inline code, and blockquotes.
Insert and resize tables with custom column widths, header rows, and merged cells.
Upload images directly into page content or link to externally hosted images with alt text.
Paste a YouTube URL to embed a responsive video player inline in your content.
Add hyperlinks to any selected text, with options to open in a new tab.
Ordered (numbered) and unordered (bulleted) lists, with nested list support.
## Blog
The blog lets you publish articles, announcements, guides, or any time-sensitive content under a `/blog/` URL structure. Blog posts are indexed by search engines and can be linked from your storefront navigation.
### Creating a blog post
1. Go to **Online Store → Blog Posts** in your admin.
2. Click **New Post** and enter a **title**.
3. Write the post body in the rich text editor.
4. Set the **status** to `Draft` or `Published`.
5. Save the post. Cartble triggers an on-demand storefront update so the post is live immediately.
### Blog post status
| Status | Behavior |
| ------------- | ----------------------------------------------------------------------- |
| **Draft** | Post is saved but not visible on the storefront or in search engines. |
| **Published** | Post is live at `/blog/[slug]` and eligible for search engine indexing. |
### Linking blog posts in navigation
Published blog posts can be referenced by their URL using a **custom** navigation item in the Navigation editor. You can also link to the blog index page (`/blog`) to give customers a single entry point for all your posts.
## SEO fields
Both pages and blog posts have dedicated SEO fields that you fill in from the editor sidebar:
| Field | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Meta title** | The `
` tag for the page — shown in browser tabs and search results. Keep it under 60 characters. |
| **Meta description** | The summary shown in search result snippets. Aim for 130–155 characters that accurately describe the content. |
<Tip>
If you leave the SEO fields blank, Cartble falls back to the page title and a truncated version of the content. Always fill in custom SEO fields for your most important pages to improve click-through rates from search engines.
</Tip>
# Add, edit, and manage products in your Cartble store
Source: https://help.cartble.com/store/products
Learn how to create, organize, and manage your catalog resources — from physical products to digital files, services, and subscriptions.
In Cartble, everything you sell is called a **Resource**. The term is intentionally broad: a resource can be a physical product, a digital file, a bookable service, or a recurring subscription — your active blueprint determines the language you see in the admin (for example, a food blueprint shows "Dishes" instead of "Resources"). This unified model means the same workflow applies no matter what type of store you run.
## Resource types
Cartble supports four core resource types that you set when creating an item:
<CardGroup>
<Card title="Physical" icon="box">
Tangible goods that require shipping. Supports weight, dimensions, SKU, and stock-level tracking.
</Card>
<Card title="Digital" icon="download">
Files or links delivered electronically. Supports file upload, external URL, download limits, and link expiration.
</Card>
<Card title="Service" icon="calendar">
Bookable or time-based offerings. Supports duration, staff assignment, buffer time, and capacity.
</Card>
<Card title="Subscription" icon="repeat">
Recurring-access products. Linked to a subscription bundle for billing cycle and access management.
</Card>
</CardGroup>
## Adding a product
<Steps>
<Step title="Open the catalog">
In your admin sidebar, navigate to **Catalog**, then click **New Resource** (your blueprint may show a different label, such as "New Dish" or "New Service").
</Step>
<Step title="Fill in the core details">
Enter the resource **name**, **description**, and **price**. If the item has a compare-at price (for showing a sale), enter it in the **Compare at price** field. Add a **cost per item** if you want margin tracking on the dashboard.
</Step>
<Step title="Upload images">
Drag and drop or select images. The first image becomes the default listing image. You can designate any image as the **cover image** — this is what appears in featured placements and collection cards.
</Step>
<Step title="Set stock and SKU">
Enter the current **stock level**. For physical items, add the **SKU** in the Logistics panel. The dashboard surfaces out-of-stock and low-stock alerts based on these values.
</Step>
<Step title="Assign categories">
Select one or more **categories** to organize this resource in your taxonomy. Categories drive navigation filters and on-site search. You can also assign the resource to **collections** if you want it to appear in curated groups.
</Step>
<Step title="Set status and save">
Choose a **status** — `draft` to keep it hidden while you work, `active` to publish it to the storefront, or `archived` to hide it without deleting it. Click **Save** to create the resource.
</Step>
</Steps>
<Tip>
Mark a resource as **Featured** and set a clear **cover image** to make it eligible for homepage featured sections. Featured resources are prioritized in the Featured Collection storefront section.
</Tip>
## Product variations
If a product comes in multiple options — such as different sizes, colors, or materials — you can use variation groups to manage each combination with its own price, stock, and SKU.
**To add variations:**
1. Enable **Has Variations** on the resource form.
2. Create one or more **Variation Groups** (e.g., `Size` with options `S`, `M`, `L`, `XL`; or `Color` with options `Black`, `White`).
3. Cartble generates a **variation matrix** — one entry per combination (e.g., `Size: M / Color: Black`).
4. For each combination, set the individual **price**, **compare-at price**, **stock**, and **SKU**.
<Info>
When variations are active, the top-level price acts as a fallback display price. Stock and SKU are tracked per variation item, not at the parent level.
</Info>
## Modifier groups
For food and service resources, you can attach **modifier groups** — optional or required add-ons that customers configure at checkout. Common examples include sauce choices, extra toppings, or session add-ons.
Each modifier group has:
* A **name** (e.g., "Choose your sauce")
* A **min selection** and **max selection** to control how many options a customer must or can pick
* A list of **modifiers**, each with its own name and additional price
## Digital resources
When the resource type is set to **Digital**, the Logistics panel is replaced with digital delivery fields:
| Field | Description |
| ------------------------- | ------------------------------------------------------------------------------ |
| **Digital file** | Upload a file directly to Cartble's storage |
| **External URL** | Paste a link to a file hosted elsewhere (e.g., Google Drive, Dropbox) |
| **Download limit** | Maximum number of times the link can be downloaded (leave blank for unlimited) |
| **Link expiration days** | Number of days after purchase before the download link expires |
| **Delivery instructions** | Custom message shown to the buyer after purchase |
## Metafields
Metafields let you attach custom structured data to any resource — useful for technical specifications, certifications, compatibility information, or any attribute your theme or integrations need. Each metafield has a **key**, **label**, **value**, and a **visible** toggle that controls whether it renders on the storefront.
## Product statuses
| Status | Behavior |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| **Draft** | Not visible on the storefront. Use while building out the resource. |
| **Active** | Live and purchasable on the storefront. |
| **Archived** | Hidden from the storefront but preserved in your catalog. Useful for seasonal items or discontinued products. |
# Theme Editor: customize your Cartble storefront design
Source: https://help.cartble.com/store/theme-editor
Use the Spark theme editor to customize colors, fonts, and layout sections — and build page-specific designs with a live preview before publishing.
Cartble's default storefront theme is called **Spark**. It's a modern, conversion-optimized theme built around a section-based layout system — every page is assembled from modular sections that you can add, remove, reorder, and configure without touching any code. The Theme Editor in your admin gives you a live canvas where every change previews in real time before you publish.
## How sections work
A section is a self-contained content block: a hero banner, a product grid, a newsletter form, a map — each one is independent and configurable. You stack sections vertically to build a page. Because sections are modular, you can mix and match them freely across different page types, and the same section type can appear multiple times on one page with different settings each time.
## Available sections
Spark ships with the following sections, each configurable from the Theme Editor:
<CardGroup>
<Card title="Hero" icon="image">
A full-width banner with headline, subheadline, background image or video, and a call-to-action button. The primary attention-grabber for your homepage or landing pages.
</Card>
<Card title="Featured Collection" icon="grid-2">
Displays a product grid from a chosen collection. Ideal for showcasing best-sellers, new arrivals, or any curated group on your homepage.
</Card>
<Card title="FAQ" icon="circle-question">
An expandable accordion of frequently asked questions. Configure question-answer pairs directly in the section settings.
</Card>
<Card title="Image Slider" icon="images">
A carousel of images with optional captions and links. Use for brand campaigns, lookbooks, or multi-image promotions.
</Card>
<Card title="Marquee" icon="arrow-right-to-bracket">
A horizontally scrolling text or logo strip — great for announcing promotions, featuring brand logos, or adding kinetic energy to a page.
</Card>
<Card title="Newsletter" icon="envelope">
An email sign-up form with a headline and call-to-action. Captures subscriber emails for your marketing list.
</Card>
<Card title="Rich Text" icon="align-left">
A freeform content block supporting headings, body text, lists, and inline formatting. Use for mission statements, editorial copy, or informational sections.
</Card>
<Card title="Stats Counter" icon="chart-bar">
Animated number counters that highlight key business metrics — years in business, customers served, products sold, and similar.
</Card>
<Card title="Team Grid" icon="users">
A staff or team member grid with photos, names, and roles. Ideal for About Us pages.
</Card>
<Card title="Video Banner" icon="circle-play">
A full-width video background section with optional overlay text and a CTA button.
</Card>
<Card title="Image With Text" icon="image-landscape">
A side-by-side layout with an image on one side and text content on the other. Good for feature callouts and brand storytelling.
</Card>
<Card title="Features Grid" icon="table-cells">
A grid of feature cards with icons, titles, and short descriptions. Use to highlight your store's selling points or service benefits.
</Card>
<Card title="Google Maps" icon="map-pin">
Embeds an interactive Google Map. Useful for brick-and-mortar locations or pickup address pages.
</Card>
<Card title="Contact Form" icon="message">
A customer-facing contact form with name, email, and message fields. Submissions are forwarded to your store's support email.
</Card>
<Card title="Platform Address" icon="location-dot">
Displays your store's address and contact details from your Platform Profile. Keeps contact information consistent across pages.
</Card>
</CardGroup>
## Page-specific layouts
Sections are organized by **page type**. Each page type has its own section stack that you configure independently:
| Page type | Description |
| ------------ | -------------------------------------------- |
| `index` | Your storefront homepage |
| `resource` | Individual product/service/dish detail pages |
| `collection` | Collection listing pages |
| `search` | Search results page |
| `contact` | Your Contact page |
| `about_us` | Your About Us page |
Navigate between page types in the Theme Editor using the page selector at the top of the editor panel. Sections you add to `index` don't affect `collection` pages, and vice versa.
## Reordering and configuring sections
**To add a section:**
1. Open the Theme Editor from **Online Store → Theme Editor**.
2. Select the page type you want to edit.
3. Click **Add Section** and choose a section type from the list.
4. The new section appears at the bottom of the stack — drag it to the desired position.
**To configure a section:**
1. Click on any section in the editor sidebar to expand its settings panel.
2. Update the fields — text, images, links, colors, and layout options — in the panel.
3. The preview canvas updates in real time as you type.
**To reorder sections:**
Drag the section handle (⋮⋮) up or down in the sidebar list to change the order. The preview updates immediately.
**To remove a section:**
Click the trash icon on any section in the sidebar. The section is removed from the page layout.
## Global theme configuration
Beyond individual sections, Spark exposes global settings that apply across your entire storefront:
<Accordion title="Colors">
Set your store's **primary color** and **secondary color**. These are used for buttons, links, accents, and highlights throughout the theme. Changes here propagate everywhere the theme references these color tokens.
</Accordion>
<Accordion title="Typography">
Choose a **heading font** and a **body font** from the available font library. Font choices apply globally to all text elements rendered by the theme.
</Accordion>
<Accordion title="General style">
Configure the **button style** (`rounded`, `square`, or `pill`) and a global **border radius** value (0–40 px). These settings shape the visual language of interactive elements and cards across the storefront.
</Accordion>
<Note>
All theme changes — section edits and global settings — are previewed live in the editor canvas before they reach your shoppers. Click **Publish** to push your changes to the live storefront when you're satisfied with the result.
</Note>