---
title: "Seller"
description: "The central marketplace actor — seller profile, lifecycle, registration flows, and business rules."
---

A **seller** is the central actor in a Mercur marketplace. Every product listing, order, payout, and storefront presence traces back to a seller account. This page covers the seller data model, lifecycle, and the business rules that govern how sellers operate on the platform.

## Seller Profile

Each seller account holds the following core fields:


| Field           | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| `name`          | Display name shown to customers on the storefront (unique)                    |
| `handle`        | URL-friendly identifier for the seller (unique)                               |
| `email`         | Primary contact email for the seller account (unique)                         |
| `description`   | Free-text seller description, typically shown on the seller's storefront page |
| `logo`          | Seller logo or avatar                                                         |
| `banner`        | Banner image for the seller's storefront page                                 |
| `website_url`   | Seller's external website                                                     |
| `currency_code` | The single currency in which this seller operates                             |
| `is_premium`    | Operator-designated premium seller flag (see below)                           |
| `status_reason` | Optional explanation for the current status (e.g. reason for suspension)      |
| `external_id`   | Identifier in an external system (unique, optional)                           |
| `metadata`      | Arbitrary JSON metadata                                                       |


### Single Currency Per Account

Every seller account is locked to **one currency**. Prices, payouts, and subscription billing all use this currency. This constraint keeps financial reporting simple and eliminates exchange-rate ambiguity in payouts.

If a seller needs to trade in multiple currencies, the recommended pattern is to create **separate seller accounts** — one per currency. Each account operates independently with its own products, orders, and payouts.

### Professional Sellers

A seller can optionally have associated **professional details**. If present, the seller is treated as a registered business; if absent, the seller is an individual.

## Address and Payment Information

Sellers can store one or more **addresses** (warehouse, return, business) and **payment details** used for payout processing. These are managed as sub-resources of the seller account and are referenced by workflows such as fulfillment and payout settlement.

## Seller Lifecycle

A seller account moves through **four statuses** over its lifetime:

```
                ┌──────────────────┐
                │  pending_approval │
                └────────┬─────────┘
                         │ approve
                         ▼
  ┌──────────┐      ┌────────┐
  │ suspended │◄────►│  open  │
  └──────────┘      └───┬────┘
                        │ terminate
                        ▼
                  ┌────────────┐
                  │ terminated  │
                  └────────────┘
```

### Status Definitions

- `**pending_approval**` — The seller has registered but has not yet been reviewed by the platform operator.
- `**open**` — The seller is active and may list products, receive orders, and collect payouts.
- `**suspended**` — The seller's operations are temporarily frozen. Products remain in the catalog but cannot be purchased.
- `**terminated**` — The seller account is permanently closed. This status is irreversible.

### Status Transition Rules


| From               | To           | Who               | Conditions                                                |
| ------------------ | ------------ | ----------------- | --------------------------------------------------------- |
| `pending_approval` | `open`       | Operator          | Operator reviews and approves the application             |
| `open`             | `suspended`  | Operator          | Policy violation, compliance hold, or operator discretion |
| `suspended`        | `open`       | Operator          | Issue resolved, seller reinstated                         |
| `open`             | `terminated` | Operator / Seller | All prerequisites met (see below)                         |
| `suspended`        | `terminated` | Operator          | All prerequisites met (see below)                         |


## Scheduled Closures

Sellers can schedule **temporary closures** without changing their account status. Two date fields control this:

- `closed_from` — The date the closure begins
- `closed_to` — The date the closure ends

During a scheduled closure the seller's storefront shows as unavailable and new orders cannot be placed, but the account remains in `open` status. This is designed for holidays, seasonal breaks, or planned downtime. Once `closed_to` passes, the seller automatically resumes normal operation.

Scheduled closures are **not a status** — they overlay on top of the current status and do not affect status transition rules.

## Premium Sellers

The `is_premium` flag is set **exclusively by the platform operator**. Sellers cannot designate themselves as premium. This flag is used for storefront features such as:

- Featured placement in search results or category pages
- Visual badges or highlights on the seller's profile
- Priority in marketplace curation

The specific storefront behavior tied to premium status is determined by the frontend implementation.

## Registration Flows

There are **two methods** for creating a seller account:

1. **Operator-created** — The platform operator creates the seller account directly via the admin dashboard. The account can be set to `open` immediately, bypassing `pending_approval`.
2. **Self-registration** — The seller registers through the public-facing registration flow. The account enters `pending_approval` status and waits for operator review.

## Business Rules Summary

- A seller account operates in **exactly one currency**
- The presence of `professional_details` determines whether the seller is a registered business
- Only the **operator** can approve, suspend, or reinstate sellers
- **Termination** is irreversible and requires all orders and payouts to be resolved
- Scheduled closures are **date-driven** and do not change account status
- **Premium** designation is operator-only and influences storefront presentation
- Every seller account must have at least one [member](/core-concepts/seller-members) with an admin role