Skip to main content
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:
FieldDescription
nameDisplay name shown to customers on the storefront (unique)
handleURL-friendly identifier for the seller (unique)
emailPrimary contact email for the seller account (unique)
descriptionFree-text seller description, typically shown on the seller’s storefront page
logoSeller logo or avatar
bannerBanner image for the seller’s storefront page
website_urlSeller’s external website
currency_codeThe single currency in which this seller operates
is_premiumOperator-designated premium seller flag (see below)
status_reasonOptional explanation for the current status (e.g. reason for suspension)
external_idIdentifier in an external system (unique, optional)
metadataArbitrary JSON metadata

​
Single Currency Per Account

Every seller account is locked to one currency. Prices and payouts 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

FromToWhoConditions
pending_approvalopenOperatorOperator reviews and approves the application
opensuspendedOperatorPolicy violation, compliance hold, or operator discretion
suspendedopenOperatorIssue resolved, seller reinstated
openterminatedOperator / SellerAll prerequisites met (see below)
suspendedterminatedOperatorAll 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 with an admin role