Skip to content

Merchello Documentation

Enterprise ecommerce for Umbraco v17+ — a full-featured online store with an integrated Shopify-style checkout, backoffice management UI, and a pluggable provider architecture.

Quick Start

Merchello ships as two NuGet packages on nuget.org. Both are released in lockstep -- the latest version is shown on the GitHub releases page. Replace <version> below (e.g. 1.0.0-beta.7).

# Option 1: Use the .NET template (scaffolds a complete starter site)
dotnet new install Umbraco.Community.Merchello.StarterSite::<version>
dotnet new merchello-starter -n MyStore

# Option 2: Add to an existing Umbraco v17+ project
dotnet add package Umbraco.Community.Merchello --version <version>

Then add Merchello to your Umbraco builder (see Program.cs):

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddComposers()
    .AddMerchello()  // <-- Add this
    .Build();

Configure your store in appsettings.json (see the starter site appsettings.json for a full example):

{
  "Merchello": {
    "InstallSeedData": true,
    "StoreCurrencyCode": "USD",
    "DefaultShippingCountry": "US"
  }
}

New to Merchello? Follow this path:

  1. Installation -- get the package installed and booted
  2. Starter Site Walkthrough -- a tour of the example store (homepage, category, basket, product detail)
  3. Project Structure -- understand where code lives and how layers interact
  4. Configuration Reference -- every appsettings.json key with defaults
  5. Seed Data -- populate a dev database with realistic products, customers, and orders

Documentation Sections

Building Your Store

Section What you'll learn
Getting Started Installation, project structure, configuration, and a guided tour of the starter site
Store Configuration Currency, countries, warehouses, and supplier setup
Products and Catalogue Products, variants, options, digital products, collections, filters, and inventory
Storefront Display context, price rendering, and stock availability
Shopping and Cart Basket operations and the basket REST API
Checkout The full checkout flow, sessions, addresses, shipping, discounts, and express checkout

Payments, Shipping, and Tax

Section What you'll learn
Payments Payment providers (Stripe, PayPal, Amazon Pay, Braintree, WorldPay), vaulting, refunds, payment links
Shipping Flat-rate and dynamic (UPS/FedEx) shipping, order grouping, packages, shipments
Tax Tax groups, rates, shipping tax, and providers (Manual, Avalara)

Customers, Orders, and Marketing

Section What you'll learn
Customers Customer management and automated segments
Orders and Invoices Order lifecycle, invoice editing, manual orders, statements
Discounts Percentage, fixed, buy-X-get-Y, free shipping, segment targeting
Upsells Post-purchase offers and one-click upsells
Multi-Currency Exchange rates, currency display, and rate locking

Integrations and Operations

Section What you'll learn
Fulfilment 3PL fulfilment with ShipBob and Supplier Direct
Email MJML templates, token replacement, and delivery
Webhooks Outbound webhooks with HMAC signing
Notifications Internal event system and custom handlers
Product Feeds Google Shopping feed generation
UCP Universal Commerce Protocol for AI agents
Reporting Sales analytics, KPIs, and CSV export

Extending Merchello

Section What you'll learn
Extension Manager How the plugin system discovers providers
Custom Providers Build your own payment, shipping, tax, fulfilment, and exchange rate providers
Notification Handlers React to events with custom handlers
Order Grouping Custom basket-splitting strategies

Reference

Section What you'll learn
API Reference Storefront, checkout, admin, webhook, and download APIs
Advanced Topics Factories, CrudResult, entity relationships, actions system, EF Core notes
Background Jobs All background jobs and their configuration
Caching Cache service API and invalidation
Health Checks Built-in store diagnostics
OpenAPI / Swagger Swagger UI and API documentation