Skip to main content
A store is the Seller record: the account a seller trades under on your marketplace. It holds the public profile customers see, the single currency the store settles in, and its status. Three satellite records carry its business details: an address, professional details, and bank payment details.

​
The seller record

The Seller data model (table seller, id prefix sel) is the root of everything a store owns. Offers, orders, payouts, and price lists link to it from their own modules. A seller has four unique fields besides its id:
  • name: unique among stores that aren’t deleted
  • handle: unique, URL safe, and generated from name when you omit it
  • email: unique, the store’s contact address
  • external_id: optional, unique when set, for mapping to an outside system
The service validates handle on create and update. A handle with characters that aren’t URL safe fails with an INVALID_DATA error.
This creates a store with the handle acme-supplies and the status pending_approval. It also invites owner@acme.com to join the team as an administrator.

​
Currency and regions

A store settles in one currency, set by currency_code when you create it. UpdateSellerDTO has no currency_code field, so the currency stays fixed for the life of the store. The vendor request context carries it as seller_context.currency_code. A store also links to one or more regions through the region_seller link:
  • On create: the store links to the default region of your Medusa store, plus any region_ids you pass
  • On change: linkSellerRegionsWorkflow adds and removes region links in one call
  • Rule: a store must keep at least one region, so removing the last one fails

​
Business details

Three one-to-one records hang off the seller. Each workflow that writes them creates the record when it’s missing and updates it otherwise. You remove professional details with deleteSellerProfessionalDetailsWorkflow. Deleting a seller cascades to all three records and to its pending invites, and detaches its members without deleting them.

​
Fulfillment defaults

default_leadtime_to_ship holds the number of days a store needs before it ships. It’s null on new stores, which then use the marketplace default from Settings → Marketplace. Vendors can change it on their own store.