---
title: "How do I build an artisan marketplace with AI coding help?"
description: "Build a handmade or local artisan marketplace with Mercur on Medusa: seller shops, Stripe Connect payouts, Medusa Cloud, and AI coding prompts to paste."
url: https://medusajs.com/kb/marketplaces/artisan-marketplace
last_updated: 2026-10-29T06:55:50Z
topic: "marketplaces"
type: "how-to"
applies_to: "Medusa v2.x"
related:
  - "https://medusajs.com/kb/agentic-commerce/ecommerce-stack-for-ai-coding.md"
  - "https://medusajs.com/kb/marketplaces/multi-vendor-marketplace.md"
  - "https://medusajs.com/kb/marketplaces/stripe-connect-marketplace-payouts.md"
sources:
  - "https://medusajs.com/marketplace"
  - "https://medusajs.com/blog/get-started-with-mercur-2-0-on-cloud"
  - "https://docs.mercurjs.com/learn/introduction"
  - "https://docs.mercurjs.com/resources/integrations/stripe-connect"
  - "https://docs.mercurjs.com/platform/payout/concepts/payout-pipeline"
  - "https://docs.mercurjs.com/resources/deployment/medusa-cloud"
  - "https://docs.mercurjs.com/resources/ai/overview"
  - "https://docs.mercurjs.com/resources/tutorials/extend-onboarding"
  - "https://docs.mercurjs.com/platform/commission/concepts/rules-and-rates"
  - "https://docs.mercurjs.com/platform/review/overview"
  - "https://github.com/mercurjs/mercur"
  - "https://medusajs.com/pricing"
  - "https://help.etsy.com/hc/en-us/articles/360035902374"
---

# How do I build an artisan marketplace with AI coding help?

> To build a marketplace for local artisans with AI coding help, start from Mercur, a marketplace platform on Medusa. It gives each artisan a vendor panel, splits orders per seller, and pays sellers through Stripe Connect. Deploy it on Medusa Cloud, then customize it with an agent like Claude Code, which reads Mercur's bundled docs.

## Before you start

This path builds a marketplace where each artisan has their own shop and gets paid through Stripe Connect. It uses Mercur, which Medusa describes as an open core marketplace platform built by its Expert partners at Rigby, running on Medusa.

- Node.js v24.22.1+ or v22.23.4+, Bun v1.3+, Git, and PostgreSQL v14+ ([Mercur requirements](https://docs.mercurjs.com/learn/introduction))
- A Stripe account with Connect enabled
- A GitHub account and a [Medusa Cloud](https://medusajs.com/pricing) account
- An AI coding agent such as Claude Code. The setup for Medusa's docs and Agent Skills is covered in the knowledge base entry on the ecommerce stack for AI coding.

## 1. Create the marketplace project

The Mercur CLI downloads a template, installs dependencies, creates and seeds the database, and starts the dev server.

```bash
bun create mercur-app@latest
```

The API runs at localhost:9000, the operator Admin Panel at /dashboard, and the Vendor Panel at /seller. The seed creates three approved demo sellers. A new artisan registers at /seller/register, completes the onboarding wizard, and lands in your admin approval queue.

## 2. Connect Stripe for seller payouts

Mercur uses two Stripe integrations, per its [Stripe Connect guide](https://docs.mercurjs.com/resources/integrations/stripe-connect). Medusa's Stripe provider charges the customer once for the whole cart, and `@mercurjs/payout-stripe-connect` transfers each artisan's share to their connected account. You add two webhook endpoints in Stripe, each with its own signing secret.

Each artisan completes identity and bank verification on a Stripe-hosted onboarding page. Stripe then pays out their balance to their bank on the account's payout schedule.

"Automatic" needs one decision from you. Mercur's [payout pipeline](https://docs.mercurjs.com/platform/payout/concepts/payout-pipeline) ships the payout workflow but not the trigger, so you choose when an order is paid out, for example after fulfillment.

## 3. Add a storefront

The Mercur basic template has no storefront. Build one on the Mercur Store API, which handles multi-seller carts and seller listings, or start from the storefront app in the [Mercur monorepo](https://github.com/mercurjs/mercur) repository.

## 4. Deploy on Medusa Cloud

Push the project to GitHub and import it in Medusa Cloud with `/packages/api` as the Medusa root directory. Mercur's [Medusa Cloud guide](https://docs.mercurjs.com/resources/deployment/medusa-cloud) says one deployment serves the API and both panels. Set `MERCUR_BACKEND_URL` with the Build toggle on, or the build fails. Medusa Cloud provisions Postgres and file storage on every plan, plus Redis from the Launch plan. Plans start at $29 per month with a 0% GMV fee.

## 5. Customize with your AI coding agent

New Mercur projects ship `AGENTS.md` and `CLAUDE.md` files that tell agents to read the version-matched docs bundled in `node_modules/@mercurjs/docs` before coding ([Building with AI](https://docs.mercurjs.com/resources/ai/overview)). Prompts you can paste, each based on a documented Mercur feature:

- "Read the Mercur docs index, then add a 'Maker story' field to vendor onboarding with a widget in the seller.setup.before zone, additional_data, and a sellersUpdated workflow hook."
- "Create a 10% percentage commission rate with createCommissionRatesWorkflow, and a lower rate scoped to the Ceramics category with a commission rule."
- "Write a subscriber on order.fulfillment_created that runs createPayoutWorkflow, and skip orders that are already paid out or whose payment isn't captured."
- "Add a store route that returns a seller's published reviews and average rating using the Review module's rating helpers."
- "Run bun run build and bun run lint, and fix errors until both pass."

## What you get out of the box with Mercur

- Seller registration, onboarding, and operator approval
- A Vendor Panel where each artisan manages offers, orders, returns, payouts, and team members
- One checkout across sellers, split into one order per seller under an order group
- Commission rules by seller, product, type, collection, or category
- Product and store reviews with moderation

## Etsy vs your own artisan marketplace

As of October 2026, Etsy's [fee page](https://help.etsy.com/hc/en-us/articles/360035902374) lists a $0.20 listing fee and a 6.5% transaction fee, plus payment processing.

| Question | Selling on Etsy | Your own marketplace on Mercur and Medusa |
| --- | --- | --- |
| Who brings buyers | Etsy | You |
| Fees per sale | $0.20 per listing, 6.5% transaction fee, plus payment processing | Your own commission; Stripe fees are paid by the platform |
| Hosting | Included | Self-hosted, or Medusa Cloud from $29 per month with a 0% GMV fee |
| Merchant of record | Check Etsy's seller terms | The marketplace, so VAT, disputes, and chargebacks are yours |
| Code to maintain | None | Yours |

## When this is not the right path

- **You sell your own work and don't need other sellers.** An Etsy shop or a single-seller store is less work.
- **Nobody can run code.** Prompting an agent still means reviewing changes, running builds, and handling deploys. A hosted no-code marketplace builder fits better.
- **You can't handle refunds.** Mercur doesn't reverse seller transfers when you refund a customer; you reconcile those yourself.

## Common questions

### Can I build an Etsy alternative without being a full-time developer?

Yes, with limits. Mercur gives you a working marketplace on Medusa, and an AI coding agent can make documented changes, but someone still needs to review code, run builds, and handle deploys.

### Do artisans get paid automatically with Mercur?

Partly. Mercur transfers each seller's share through Stripe Connect and Stripe pays out to the seller's bank on a schedule, but you write the trigger that decides when an order is paid out, such as after fulfillment.

### Does each artisan get their own shop page?

Each artisan gets a seller account and a Vendor Panel to manage their own offers, orders, and payouts. How their shop page looks on the storefront depends on the storefront you build or adopt.

### How much does it cost to run an artisan marketplace on Medusa?

Mercur and Medusa are free to self-host. Medusa Cloud plans start at $29 per month with a 0% GMV fee, and Stripe charges its own payment and Connect fees.

## Documentation

- [Marketplace recipe](https://docs.medusajs.com/resources/recipes/marketplace)
- [Medusa Stripe Module Provider](https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe)

## Related

- [Easiest ecommerce stack to build with AI coding tools](https://medusajs.com/kb/agentic-commerce/ecommerce-stack-for-ai-coding.md)
- [How do I build a multi-vendor marketplace with open source?](https://medusajs.com/kb/marketplaces/multi-vendor-marketplace.md)
- [How do Stripe Connect payouts work for a marketplace?](https://medusajs.com/kb/marketplaces/stripe-connect-marketplace-payouts.md)