Platform Guide

What is MercantileOS?

MercantileOS is a platform that lets you sell products online. Think of it like having your own shop on the internet. Instead of customers walking into a physical store, they visit your website, browse your products, and buy things with their credit card.

MercantileOS handles all the complicated stuff for you:

• Your online storefront - The website your customers see and shop on
• The admin dashboard - Where you manage products, orders, and everything else (that's what this guide covers)
• Payment processing - Securely accepting credit cards
• Order management - Keeping track of what people bought and shipping it to them

Your First Login

When you sign up for MercantileOS, you'll get an email with a link to your admin dashboard. Here's how to get started:

1. Click the link in your email - This takes you to your login page
2. Enter your email and password - The ones you used when signing up
3. Click "Sign in" - You're now in your dashboard!

Dashboard Overview

When you first log in, you'll see your dashboard. This is like the home base for your store. Let's look at what's on the screen:

The Sidebar (Left Side)

On the left side of the screen, you'll see a menu with different sections. This is how you navigate around:

• Dashboard - Your home page with sales stats and quick info
• Products - Add and edit the things you sell
• Orders - See what people have bought
• Customers - Info about people who've shopped with you
• Collections - Group products together (like "Summer Sale" or "Best Sellers")
• Discounts - Create coupon codes and sales
• Reviews - See and manage customer reviews
• Upsells - Suggest extra products to customers
• Content - Upload images and files
• Pages - Create pages like "About Us" or "Contact"
• Blog - Write blog posts for your store
• Themes - Change how your store looks
• Analytics - See how your store is performing
• Email - Send marketing emails
• Settings - Configure your store's settings

The Main Area (Center)

The big area in the middle shows you whatever section you've clicked on. On the dashboard, you'll see:

• Today's sales - How much money you've made today
• Recent orders - The latest orders that came in
• Top products - Your best-selling items

Adding Products

Products are the things you're selling. Let's add your first one:

1. Click "Products" in the sidebar - This shows you all your products (empty at first)
2. Click the "Add product" button - It's in the top right corner
3. Fill in the product details:
   • Title - The name of your product (e.g., "Blue Cotton T-Shirt")
   • Description - Tell customers about it. What is it? Why should they buy it?
   • Price - How much it costs (just type the number, like "29.99")
   • Images - Click to upload photos of your product
4. Click "Save" - Your product is now in your store!

Product Variants

What if your product comes in different sizes or colors? That's where variants come in.

Example: You sell a t-shirt that comes in Small, Medium, and Large, and in Blue and Red. Instead of creating 6 separate products, you create ONE product with variants.

1. On the product page, scroll to "Variants"
2. Click "Add options"
3. Add your first option:
   • Option name: "Size"
   • Values: "Small", "Medium", "Large"
4. Add another option if needed:
   • Option name: "Color"
   • Values: "Blue", "Red"
5. The system creates all combinations automatically - Small/Blue, Small/Red, Medium/Blue, etc.
6. Set the price and inventory for each variant - Maybe the Large costs a bit more?

Collections

Collections are groups of products. They help customers find what they're looking for.

Examples of collections:

• "Men's Clothing"
• "Summer Sale"
• "Best Sellers"
• "Under $50"
• "New Arrivals"

To create a collection:

1. Click "Collections" in the sidebar
2. Click "Create collection"
3. Give it a name and description
4. Add products to it - You can pick them manually or set rules (like "all products under $50")
5. Save it

Managing Inventory

Inventory means keeping track of how many of each product you have in stock.

Why it matters: You don't want to sell something you don't have! When inventory reaches zero, the product shows as "Sold Out."

1. Go to Products
2. Click on a product
3. Find the "Inventory" section
4. Enter how many you have - The system automatically subtracts when someone buys

Viewing Orders

When someone buys from your store, an order is created. Here's how to see your orders:

1. Click "Orders" in the sidebar
2. You'll see a list of all orders - Newest first
3. Click on any order to see the details

Each order shows you:

• Order number - A unique ID like "#1001"
• Customer info - Name, email, shipping address
• What they bought - The products and quantities
• Payment status - Did they pay? (Usually yes, if the order exists)
• Fulfillment status - Have you shipped it yet?

Fulfilling Orders

"Fulfilling" an order means you've packed it up and shipped it to the customer. Here's how:

1. Go to Orders and click on an order
2. Pack the items in a box - (Do this in real life!)
3. Ship it with your carrier - USPS, UPS, FedEx, etc.
4. Get the tracking number - The carrier gives you this
5. Back in MercantileOS, click "Fulfill order"
6. Enter the tracking number
7. Click "Fulfill"

The customer automatically gets an email with their tracking number!

Processing Refunds

Sometimes customers want their money back. Here's how to process a refund:

1. Go to the order
2. Click "Refund"
3. Choose what to refund:
   • The whole order? Enter the full amount.
   • Just one item? Enter that item's price.
4. Add a reason - (Optional but helpful for your records)
5. Click "Refund"

The money goes back to the customer's card automatically. It usually takes 5-10 business days to show up on their end.

Customer List

Every person who buys from your store becomes a customer. You can see them all:

1. Click "Customers" in the sidebar
2. Browse or search for customers

You can see:

• Their name and email
• How many orders they've placed
• How much they've spent total
• When they last ordered

Customer Details

Click on any customer to see their full history:

• All their orders
• Their addresses
• Notes you've added about them
• Tags you've assigned (like "VIP" or "Wholesale")

Discounts & Coupons

Discounts help you run sales and give customers special deals. There are two types:

• Discount codes - Customers type a code like "SAVE20" at checkout
• Automatic discounts - Applied automatically when conditions are met

To create a discount:

1. Click "Discounts" in the sidebar
2. Click "Create discount"
3. Choose the type:
   • Percentage - Like 20% off
   • Fixed amount - Like $10 off
   • Free shipping - No shipping charge
4. Set the discount code - Make it memorable like "SUMMER20"
5. Set any limits:
   • Minimum purchase amount?
   • How many times can it be used?
   • Start and end dates?
6. Save it

Product Reviews

Reviews help build trust with new customers. MercantileOS has reviews built in (no extra app needed!).

How reviews work:

1. Customer buys a product
2. After a few days, they get an email asking for a review
3. They write a review and give a star rating
4. You can approve or reject the review
5. Approved reviews show on the product page

To manage reviews:

1. Click "Reviews" in the sidebar
2. See pending reviews - Ones waiting for approval
3. Approve good reviews - Click the checkmark
4. Reject bad reviews - Click the X (for spam, inappropriate content, etc.)

Email Marketing

Email is one of the best ways to bring customers back. MercantileOS has email marketing built in.

Types of emails you can send:

• Campaigns - One-time emails like "Black Friday Sale!"
• Flows - Automatic emails triggered by actions, like "Welcome email when someone signs up"

Common email flows:

• Welcome series - Introduce new subscribers to your brand
• Abandoned cart - Remind people who left items in their cart
• Post-purchase - Thank customers and ask for a review
• Win-back - Re-engage customers who haven't bought in a while

Upsells

Upsells suggest additional products to customers, increasing your average order value.

Where upsells appear:

• Product page - "Customers also bought..."
• Cart page - "Add this for just $X more"
• Post-purchase - After checkout, offer a one-click add-on

1. Click "Upsells" in the sidebar
2. Click "Create upsell"
3. Choose when to show it - Product page, cart, or post-purchase
4. Choose what triggers it - When they have certain products in cart
5. Choose what to offer - The upsell product
6. Optionally add a discount - "Add this for 20% off!"
7. Save it

Predictive Intelligence

Predictive Intelligence uses AI to understand your visitors and predict who's likely to buy. It's like having a really smart salesperson who knows exactly when to help someone.

What you get:

• Intent Scoring - Every visitor gets a score from 0-100 based on their behavior. High score = likely to buy
• Visitor Segments - Automatic grouping by behavior (price-sensitive, engaged, browsing, etc.)
• Abandonment Prediction - Know when someone's about to leave before they do

1. Click "Intelligence" in the sidebar
2. See your dashboard - Active visitors, intent scores, predictions
3. Configure Intent Scoring - Adjust which behaviors matter most
4. View Visitor Segments - See how visitors are classified

A/B Testing

A/B Testing lets you test different versions of things to see what works better. Show half your visitors version A, half version B, and see which one converts more.

Two testing modes:

• Bayesian A/B Tests - Traditional 50/50 split testing with statistical analysis
• Multi-Armed Bandits - Smart testing that automatically sends more traffic to the winning variant

1. Click "Testing" in the sidebar
2. Click "Create Test"
3. Choose what to test - Headlines, images, prices, layouts
4. Set up your variants - Version A (control) and Version B (challenger)
5. Set your confidence level - 90%, 95%, or 99%
6. Start the test
7. Wait for results - The system tells you when there's a winner

Personalization

Personalization lets you show different content to different visitors based on rules you define.

Strategy types:

• Urgency - Countdown timers, "only X left" messages
• Scarcity - Low stock warnings, limited availability
• Social Proof - "X people viewing this", recent purchases
• Exit Intent - Popups when someone's about to leave

1. Click "Personalization" in the sidebar
2. Create a strategy - Choose what type (urgency, scarcity, etc.)
3. Set targeting rules:
   • By UTM source (show different content to Facebook vs Google traffic)
   • By cart value (target high-value carts)
   • By device (mobile vs desktop)
   • By location (country, state)
   • By time (time of day, day of week)
4. Configure the content - What message to show
5. Activate it

Payment Recovery

Payment Recovery automatically tries to recover failed payments. When someone's card is declined, the system intelligently retries based on why it failed.

Why payments fail:

• Insufficient funds (retry in a few days when they get paid)
• Card expired (send an email to update)
• Temporary bank issue (retry immediately)
• Fraud suspected (don't retry, investigate)

1. Click "Recovery" in the sidebar
2. View your dashboard - Pending retries, recovered payments, success rate
3. Configure retry rules - When and how often to retry each decline type
4. Set up recovery sequences - Automated emails + SMS to customers

Themes

Themes control how your store looks to customers. Think of it like choosing the paint and furniture for a physical store.

Two ways to edit themes:

• Visual Builder - Drag-and-drop editor, no code needed
• Code Editor - Edit Liquid templates directly (for developers)

Visual Page Builder

The Visual Builder lets you create pages by dragging and dropping sections. No coding required.

1. Click "Themes" in the sidebar
2. Click "Customize" on your theme
3. Click "Visual Builder"
4. Add sections from the library:
   • Hero - Big banner at the top
   • Featured Products - Show off products
   • Image with Text - Image + description side by side
   • Testimonials - Customer quotes
   • FAQ - Questions and answers
   • Newsletter - Email signup form
   • Logo List - "As seen in" logos
   • Video - Embed videos
   • And more...
5. Drag to reorder - Move sections up and down
6. Click a section to edit it - Change text, images, colors
7. Preview on different devices - Desktop, tablet, mobile buttons
8. Save (Cmd+S)

Code Editor

For advanced customization, use the Code Editor to edit Liquid templates directly.

1. Click "Themes" in the sidebar
2. Click "Customize" on your theme
3. You're in the Code Editor by default
4. Browse files - Layout, templates, sections, snippets
5. Click a file to edit
6. Save your changes

Pages

Pages are static content like "About Us," "Contact," or "Shipping Policy."

1. Click "Pages" in the sidebar
2. Click "Create page"
3. Enter a title - Like "About Us"
4. Write your content - Use the editor to format text, add images, etc.
5. Save and publish

Your page will be available at yourstore.com/pages/about-us

Blog

A blog helps with SEO (showing up in Google) and gives customers useful content.

1. Click "Blog" in the sidebar
2. Click "Write post"
3. Enter a title
4. Write your post - Tips, guides, news, etc.
5. Add a featured image - The main image for the post
6. Save and publish

Content & Files

The Content section is where you upload and manage all your files - images, videos, PDFs, etc.

1. Click "Content" in the sidebar
2. Click "Upload" or drag files onto the page
3. Your files are now available to use in products, pages, etc.

General Settings

Click "Settings" in the sidebar to access all your store settings. The "General" section covers:

• Store name - What your store is called
• Contact email - Where customers can reach you
• Store address - Used for shipping calculations and invoices
• Currency - What currency you sell in (USD, EUR, etc.)

Payments

Set up how you accept payments:

1. Go to Settings > Payments
2. Connect a payment provider - Like Stripe or PayPal
3. Follow their setup instructions - Usually involves creating an account with them
4. Once connected, you can accept credit cards!

Shipping

Set up shipping rates for your store:

1. Go to Settings > Shipping and delivery
2. Create shipping zones - Groups of countries/regions
3. Add rates for each zone:
   • Flat rate - Same price no matter what (e.g., $5 shipping)
   • Free shipping - No charge
   • Price-based - Different rates based on order total
   • Weight-based - Different rates based on weight

Advanced Shipping Features

MercantileOS includes advanced shipping features that are typically only available through paid apps on other platforms (saving you $9-29/month).

Postal Code Targeting

Target specific ZIP codes or postal code ranges for precise shipping zones:

• Exact ranges: Target 90001-90099 for specific neighborhoods
• Wildcards: Use 900* to match all codes starting with 900
• Use cases: Local delivery zones, regional pricing, urban vs rural rates

USPS Zone-Based Pricing

Calculate accurate USPS rates based on pre-loaded zone charts:

• ~43,000 ZIP combinations: Complete USPS zone reference data built-in
• Distance-based pricing: Charge more for farther destinations automatically
• Rate tables: Set different rates for each zone (1-8)

Dimensional Weight

Prevent undercharging on large, lightweight packages:

• Automatic calculation: Uses (L × W × H) / 166 formula
• Billable weight: Charges based on whichever is greater - actual or dimensional weight
• Package definitions: Define standard box sizes for your products

Smart Package Optimization

Reduce shipping costs by optimizing multi-item orders:

• Bin-packing algorithm: Automatically fits items into the fewest packages
• 15-35% savings: Reduces dimensional weight charges significantly
• First-Fit Decreasing: Industry-standard optimization method

To enable advanced shipping features, go to Settings > Shipping Advanced in your dashboard.

Taxes

Set up tax collection:

1. Go to Settings > Taxes and duties
2. Set your tax regions - Where you need to collect tax
3. Enter tax rates - The percentage for each region

Advanced Tax Features

MercantileOS includes a comprehensive tax management system that's smarter than Shopify and doesn't require expensive third-party services like TaxJar or Avalara (saving you $19-99/month).

Multi-Jurisdictional Tax Calculation

Automatically calculate combined taxes from multiple jurisdictions:

• City + County + State: Automatic resolution based on customer address
• All 50 US states: Pre-loaded with current tax rates
• 3,143 counties: Expandable county database for precise local rates
• Major cities: City-level tax rates for accurate calculations

Economic Nexus Tracking

Monitor your sales to avoid surprise tax obligations:

• Automatic tracking: Monitors revenue and transactions by state
• Threshold alerts: Warns you at 75% and 90% of $100k/200 transaction limits
• Three nexus types: Physical presence, economic, and marketplace facilitator
• Auto-collect option: Automatically start collecting when threshold is crossed

Product Tax Categories

Handle complex tax exemptions by product type:

• 8 tax categories: Standard, clothing, food, digital goods, services, and more
• State-specific rules: Automatically applies exemptions (e.g., clothing under $110 in NY)
• Compliance-ready: Follows current state tax laws

Tax Exemption Certificates

Manage wholesale and nonprofit exemptions:

• Certificate tracking: Upload and store customer exemption certificates
• Expiration dates: Automatic reminders before certificates expire
• Types supported: Resale, nonprofit, government, and other
• Auto-apply: Automatically exempts qualifying customers at checkout

Historical Tax Records

Full audit trail for compliance:

• Rate versioning: Tracks when tax rates change
• Order-level details: Breakdown by jurisdiction for every order
• Audit-ready reports: Export tax data for accountants and audits

To enable advanced tax features, go to Settings > Tax Advanced in your dashboard.

Domains

Your domain is your store's web address (like "mystore.com").

1. Buy a domain - From a registrar like Namecheap, GoDaddy, or Google Domains
2. Go to Settings > Domains
3. Click "Add domain"
4. Enter your domain name
5. Follow the DNS instructions - You'll need to add some records at your domain registrar
6. Wait for it to connect - This can take up to 48 hours

Users & Permissions

If you have a team, you can give them access to your store:

1. Go to Settings > Users and permissions
2. Click "Add user"
3. Enter their name and email
4. Choose their role:
   • Admin - Full access to everything
   • Staff - Can manage orders and products but not settings
5. Click "Create user" - They'll get an email to set up their account

Getting Help

Stuck on something? Here's how to get help:

• Email Support: support@mercantileos.com
• Documentation: You're reading it! Browse the sidebar for more guides.
• API Guide: For developers integrating with MercantileOS

We're real humans who actually want to help you succeed. No AI chatbots, no runaround.