A marketplace is not just a catalog with a checkout button. It coordinates tenants, buyers, sellers, moderators, listings, orders, payments, fulfillment, disputes, notifications, private data, and operator recovery. Each part changes on a different clock, so one overloaded status field creates failures that are difficult to explain or repair.
This guide builds the smallest useful marketplace contract first: seller-owned listings move through draft, review, and publication; orders move through explicit payment and fulfillment states; server authorization protects every tenant; provider events are idempotent and reconcilable; and exports, retention, and recovery are designed before real customer data arrives.
QUICK ANSWER
How do you create a marketplace website?
Define who buys, sells, moderates, and operates the marketplace, then model listings and orders as separate state machines. Enforce tenant and role access on the server, make creates and payment events idempotent, keep notifications outside durable transactions, test failure and recovery paths, and only then publish the workflow over HTTPS.
Write the marketplace contract before designing the catalog
Start with two fictional tenants, one seller, one buyer, one moderator, and one operator. That fixture reveals cross-tenant access, moderation, duplicate-event, privacy, and recovery errors that stay hidden when every test runs as the creator.
- Tenant, user, and role boundaries: Name the tenant or marketplace scope, seller ownership rule, buyer access, moderator actions, operator powers, support boundary, and server denial for every list, detail, mutation, export, and recovery action.
- Listing and order state diagrams: Define listing draft, review, published, and rejected transitions separately from payment pending, paid, fulfillment, complete, refund requested, refunded, and dispute. Name who may trigger each transition and what version conflict means.
- Provider and fulfillment decisions: Decide whether the first release takes no payment, sends users to a documented provider-hosted flow, or needs a custom server integration. Record provider account, plan, region, signature, payout, tax, refund, and dispute constraints before promising behavior.
- Moderation, privacy, retention, export, and recovery owners: List what may be published, what PII is necessary, when terminal-order buyer details are redacted, who may export data, how disputes affect retention, and which records and idempotency decisions must survive recovery.
Choose the transaction boundary that matches the first proof
The catalog, order, payment, fulfillment, and communication boundaries do not have to launch together. A smaller first release is safer when its manual steps are explicit and operators can see which state is authoritative. If the core job is user-submitted offers with moderation, the build a classifieds app path focuses on submission, review, reporting, expiry, and removal. For a curated catalog of people, services, or places, the build a directory website path focuses on taxonomy, duplicate control, freshness, and corrections. This guide keeps the broader marketplace boundary: buyers, sellers, orders, optional payments, fulfillment, and disputes.
| Approach | Best for | Tradeoff |
|---|---|---|
| Request or reservation marketplace without online payment | Testing supply, demand, listing quality, matching, and fulfillment before choosing a payment and payout model. | It reduces payment complexity but requires a clear manual confirmation, cancellation, and completion process outside the site. |
| Provider-hosted checkout or payment link | A first paid workflow where the chosen provider supports the country, business type, payment method, refund, and marketplace obligations you need. | The provider handles sensitive payment entry, but your server still needs order identity, signed event verification, duplicate handling, reconciliation, refund policy, and customer support. |
| Custom marketplace payment and payout integration | A validated marketplace with concrete split-payment, seller onboarding, payout timing, tax, refund, dispute, and compliance requirements. | It provides more control but adds provider approval, restricted server credentials, webhook operations, payout ledgers, compliance review, and a larger incident surface. |
Recommended:Start with a payment-pending local order and an external provider boundary, or no online payment at all. Never store card data in the marketplace application. Add live provider events only after exact duplicate, changed-payload, out-of-order, reconciliation, refund, dispute, and partial-failure behavior is tested with fictional records.
Create a marketplace website step by step
Define marketplace roles, model moderated listings and stateful orders, protect server actions, connect optional providers through a reconciliation boundary, test failures, publish, and operate the workflow.
STEP 01
Define the smallest complete marketplace promise
Choose one category, one listing type, one buyer action, and one fulfillment outcome.
Write the buyer journey from search or category browsing to order creation and completion. Write the seller journey from draft listing to review, publication, order fulfillment, cancellation, refund, or dispute.
Name where the marketplace stops. If payment, shipping, identity verification, tax, seller payout, or dispute resolution is manual or provider-owned, state that boundary in the product and support process.
Expected result: The first release has one observable job for buyers, sellers, moderators, and operators without implying an unbuilt payment or payout service.
Verify it: Walk one fictional order from a seller draft to buyer completion and identify the owner, state, next allowed action, and recovery action at every step.
STEP 02
Model tenants, roles, and records independently
Separate identity and ownership from listing, order, provider-event, notification, and audit state.
Create tenant, user, membership or role, listing, order, provider event, reconciliation item, notification attempt, export, and audit records as required. Give each a stable ID, tenant scope, timestamps, and a version where concurrent writes matter.
Derive tenant, user, and role from the server session. Never trust a browser-supplied seller ID, tenant ID, role, price, payment result, or transition name as authorization.
type ListingState = 'draft' | 'review' | 'published' | 'rejected'
type OrderState =
| 'payment_pending'
| 'paid'
| 'fulfillment'
| 'complete'
| 'refund_requested'
| 'refunded'
| 'dispute'
type ActorRole = 'buyer' | 'seller' | 'moderator' | 'operator'Expected result: A user role, listing state, order state, provider event, delivery attempt, or audit record can change without silently rewriting the others.
Verify it: Create the same listing and order IDs in two fictional tenants, then verify that every list, detail, mutation, and export is scoped before the record is returned.
STEP 03
Build listing ownership and moderation transitions
Make draft, review, publication, and rejection explicit server decisions.
Allow the owning seller to edit a draft and submit it for review. Allow only a moderator or operator in the same tenant to publish or reject a reviewed listing. Decide whether rejection returns to draft or creates a separate revision.
Store the expected record version with every transition. Reject a stale moderation or seller update instead of overwriting a newer decision with last-write-wins behavior.
Expected result: A listing cannot become publicly visible by changing browser state, skipping review, crossing tenants, or replaying a stale update.
Verify it: Attempt publication as the seller, another tenant, and a moderator with a stale version, then publish once as the authorized current-version moderator.
STEP 04
Make order creation and transitions idempotent
Represent one business action once even when requests retry or arrive concurrently.
Create a payment-pending order from a published listing with a client-independent idempotency key and a server fingerprint of the intended operation. Return the existing result for an exact retry and reject the same key with changed buyer, listing, quantity, or amount.
Allow only documented transitions. Require the expected version for buyer, seller, moderator, operator, and worker actions so two concurrent fulfillment, refund, or completion attempts cannot both win.
Expected result: One intended purchase creates one order, changed retries fail closed, and every successful transition has one previous and one next state.
Verify it: Repeat the same create request, change its quantity under the same key, submit two updates with one version, and confirm counts, state, version, and audit records are deterministic.
STEP 05
Reconcile optional provider events on the server
Treat provider payment state as external evidence, not a trusted browser response.
For a provider integration, verify the event signature against the raw request body using a server-side endpoint-specific secret. Store the stable event ID, type, order reference, and safe fingerprint before applying a local transition.
Return the prior result for an exact duplicate. Reject the same event ID with changed content. Put a valid but currently impossible event into pending reconciliation, then let an authorized operator apply it after the required preceding state exists.
Expected result: Duplicate payment confirmation applies once, changed duplicates fail closed, and out-of-order refund or dispute evidence remains visible until reconciled.
Verify it: Replay one verified event, alter its payload under the same ID, send refund before paid, then reconcile after the order reaches the valid state and compare event, order, and audit records.
STEP 06
Separate notifications, privacy, export, and recovery
Keep side effects and data lifecycle rules outside the durable order transition.
Commit the order transition before sending email, SMS, push, or provider notifications. Store a delivery attempt with its own idempotency key, error, retry count, and final status so a message failure never repeats or erases the order.
Export only approved fields after server authorization. Redact no-longer-needed buyer PII under the retention policy while preserving bounded operational and audit facts. Include records, versions, idempotency decisions, provider-event fingerprints, and audit history in recovery.
Expected result: A failed notification can retry independently, an authorized export is bounded, retained PII is explainable, and a restored system rejects prior duplicate operations consistently.
Verify it: Fail a notification after a durable order change, retry delivery, run authorized and unauthorized exports, apply retention, restore a recovery bundle, and replay a prior idempotency key.
STEP 07
Run access, transition, duplicate, partial-failure, and restore tests
Test the state machine directly before trusting the visible marketplace screens.
Download the marketplace state-machine artifact, extract it, run npm test with a current Node.js release, and inspect the eight deterministic scenarios. The package has no runtime dependencies, network calls, provider credentials, or real customer data.
Add product-specific fixtures for price calculation, inventory, scheduling, shipping, cancellation windows, refund authority, moderation policy, and provider behavior. Assert records and audit state, not only status codes or toast messages.
Expected result: Cross-tenant and role access is denied, invalid or stale transitions fail closed, duplicates apply once, out-of-order events reconcile, side effects retry independently, and restore preserves prior decisions.
Verify it: Run the artifact tests twice, confirm all eight pass, compare the ZIP SHA-256 with the evidence note, and review every product-specific test with its final record counts and state.
STEP 08
Publish and run a fictional production smoke test
Verify the final HTTPS environment without exposing live credentials or customer data.
Publish the core marketplace, create two labeled fictional tenants, submit and moderate one listing, create one order, exercise the selected payment or manual-confirmation boundary, move through fulfillment, and test one denial and one notification failure.
Check final-domain sessions, environment separation, raw provider signature handling when applicable, logs, export authorization, retention, backup, restore procedure, and cleanup of fictional records.
Expected result: The final environment completes one bounded marketplace workflow while cross-tenant, moderation, payment, fulfillment, privacy, and operator boundaries match the documented contract.
Verify it: Save bounded request, tenant, listing, order, event, and delivery IDs, repeat protected requests as the wrong tenant and role, then archive or delete fixtures under the retention policy.
STEP 09
Monitor reconciliation, disputes, exports, and recovery
Operate the marketplace from explicit records instead of support guesses.
Monitor denied actions by reason, stale-version conflicts, listings awaiting review, orders stuck in payment or fulfillment, provider events pending reconciliation, duplicate conflicts, notification retries, refunds, disputes, export requests, retention jobs, and operator overrides.
Write recovery runbooks for one listing, one order, one provider event, one tenant export, and whole-system restore. Every repair should be authorized, idempotent, audited, and safe to retry.
Expected result: Operators can identify the authoritative record and safe next action without editing production rows blindly or replaying payment and notification side effects together.
Verify it: Run a tabletop incident for an out-of-order refund, failed notification, stale fulfillment update, disputed order, unauthorized export, and restored duplicate event using fictional IDs.
Test the business boundary, not only the happy checkout
Use two tenants and ordinary roles, then assert record counts, state, versions, event fingerprints, delivery attempts, exports, and audit facts after every request.
| Test | Scenario | Expected result |
|---|---|---|
| happy path | A seller submits a draft, a moderator publishes it, a buyer creates one payment-pending order, a verified provider event marks it paid, and the seller completes fulfillment. | One listing and one order follow only allowed transitions with increasing versions and bounded audit entries. |
| invalid input | A wrong tenant reads an order, a seller publishes directly, an unsigned event arrives, and a stale fulfillment update targets the current order. | Every action fails closed without private fields, state changes, provider application, notifications, or ambiguous audit success. |
| retry | Repeat one order create, replay one exact provider event, reuse each ID with changed content, fail a notification after commit, and retry after recovery restore. | Exact retries return the stable result, changed reuse is rejected, the order never repeats, and notification retry changes only delivery state. |
| production smoke | On the published HTTPS site, use two fictional tenants to moderate a listing, create and fulfill one order, test one denial, run a bounded export, and rehearse recovery. | The final environment preserves the documented tenant, role, state, provider, notification, privacy, export, and recovery boundaries. |
Marketplace failures should point to one authoritative record
The visible symptom is often one step away from the cause. Compare the listing, order, provider event, notification, version, and audit records before retrying a side effect.
| Symptom | Likely cause | Check | Fix |
|---|---|---|---|
| A buyer or seller can read another tenant's order | A detail, list, mutation, or export path queried by record ID before applying the server-derived tenant and role scope. | Replay the known ID as an ordinary user in the other tenant and inspect the raw response plus server authorization context. | Require tenant and allowed action in every private record lookup, return a bounded denial, and keep the cross-tenant regression test. |
| A listing appears without moderator review | Publication is a writable field or client action instead of a server transition from review by a current moderator or operator. | Inspect the previous state, actor role, tenant, expected version, and audit entry for the publication change. | Centralize allowed transitions, require review plus current version, and reject seller, cross-tenant, and stale publication attempts. |
| Payment or refund applies twice | The handler did not persist a stable provider event ID and safe fingerprint before changing the order, or reused request idempotency for event deduplication. | Compare provider event IDs, fingerprints, processing results, order versions, and audit records without logging the full payment payload. | Persist exact event identity once, return the prior result for exact duplicates, reject changed reuse, and make the local transition idempotent. |
| The provider says paid but the local order remains pending | The verified event was out of order, failed after persistence, referenced the wrong order, or could not pass the current transition and version rules. | Inspect signature result, stored event status, order reference, current order state and version, pending reconciliation reason, and audit trail. | Keep the verified event, expose pending reconciliation to an authorized operator, repair the preceding state, and retry only the local application. |
| The order saved but the user received an error | A notification or downstream side effect failed after the durable transition and the response treated both operations as one transaction. | Compare the order version and audit entry with the separate notification attempt, error, and retry count. | Return the durable order result, record the failed delivery, and retry notification with its own idempotency key without repeating the order action. |
| A restored system accepts a duplicate order or event again | The recovery bundle restored domain rows but omitted idempotency decisions, provider-event identities, versions, or audit ordering. | Compare pre-recovery and restored idempotency keys, fingerprints, event IDs, versions, and record counts, then replay the same request. | Treat idempotency and event identity as durable business state, include them in backup and restore, and test replay after every recovery change. |
Publish only what the marketplace can explain and recover
Deploy
Separate development and production provider accounts, endpoints, signing secrets, domains, cookies, storage, and notification senders. Do not copy test credentials or fictional payment assumptions into production.
Run a final-domain smoke test with fictional buyer, seller, moderator, and operator accounts. Verify one denial, moderation transition, order lifecycle, provider or manual-confirmation boundary, notification failure, export, and cleanup.
Monitor
Monitor denied actions, stale conflicts, moderation queue age, order age by state, event verification and reconciliation, duplicate conflicts, notification retry age, disputes, refunds, export activity, retention jobs, and operator repairs.
Log stable bounded IDs, state changes, actor role, tenant, result, and error class. Keep secrets, raw provider payloads, tokens, addresses, messages, and private listing content out of routine logs.
Recover
Back up domain records, versions, idempotency decisions, provider-event fingerprints, notification attempts, approved export facts, and bounded audit order. Test restore into an isolated environment before relying on it.
Repair one record through authorized idempotent commands, not direct database edits. Reconcile payment, refund, dispute, fulfillment, and delivery records separately so recovery never repeats unrelated side effects.
Marketplace security starts with server-derived scope
A marketplace handles records from multiple parties whose interests differ. Design every read, write, event, export, and repair as a server-authorized action with a bounded audit result.
- Resolve identity, tenant, role, and allowed action on the server for every private request; never authorize from hidden buttons or browser tenant IDs.
- Scope listing drafts, orders, files, messages, search indexes, caches, jobs, exports, and recovery commands before retrieving private records.
- Keep provider API credentials and webhook signing secrets in server-side environment configuration, separated by environment and absent from source, URLs, analytics, and logs.
- Verify provider signatures against the raw request body, persist stable event identity once, and reject the same event ID when its safe fingerprint changes.
- Use idempotency keys for retryable creates and commands, optimistic versions for concurrent record changes, and separate identities for notification delivery attempts.
- Collect only necessary buyer and seller PII, document retention and redaction by order state, and restrict exports to approved fields and authorized roles.
- Rate-limit sign-in, listing submission, order creation, messages, exports, event endpoints, and operator repairs according to their abuse and cost boundaries.
- Keep moderation, refunds, disputes, overrides, exports, retention, and recovery auditable with bounded facts rather than copied private payloads.
- Review provider marketplace, payment, payout, tax, refund, dispute, country, and business-type requirements with qualified specialists before live transactions.
Marketplace website questions
Can I create a marketplace website with Playcode?
You can use Playcode AI to build the frontend, server logic, database-backed records, authentication, tests, and hosting path for a marketplace workflow. The quality of the result depends on a precise tenant, role, listing, order, moderation, provider, privacy, and recovery brief.
What should a marketplace MVP include?
Include one listing type, buyer and seller accounts, one moderation path, one order lifecycle, server authorization, idempotent creates, a manual or explicit provider boundary, operator visibility, notifications, privacy rules, export, monitoring, and recovery. Add categories, messaging, reviews, payouts, and automation only when the core workflow proves useful.
Do I need online payments in the first version?
No. A request, reservation, quote, or manual-confirmation marketplace can validate supply, demand, listing quality, matching, and fulfillment with less operational risk. If payment is necessary, choose a provider-supported model and keep local orders separate from provider events.
Does Playcode provide native marketplace payments or seller payouts?
This guide does not claim a native payment, escrow, split-payment, payout, tax, fraud, or dispute service. A live integration requires your chosen provider account and plan, server-side credentials, signed events, idempotency, reconciliation, policy review, and production tests.
Why are listing and order states separate?
A listing can be drafted, reviewed, published, rejected, paused, or archived independently from any buyer order. An order can be pending payment, paid, fulfilled, completed, refunded, or disputed. Separate state machines make authorization, support, retries, reporting, and recovery explainable.
How do I prevent duplicate marketplace orders?
Require a stable idempotency key for the intended create operation and store a server fingerprint of its buyer, tenant, listing, quantity, and pricing decision. Return the original result for an exact retry, but reject the same key when the intended operation changes.
How should marketplace webhooks be handled?
Verify the signature against the raw request body, store the provider event ID and safe fingerprint once, apply allowed transitions idempotently, reject changed reuse, and hold valid out-of-order events for operator reconciliation. Never trust the checkout return page as payment proof.
What happens if email fails after an order succeeds?
Keep the durable order authoritative and record the email or notification as a separate failed delivery attempt. Retry only the notification with its own idempotency identity. Do not roll back or repeat the order because a downstream message failed.
What should a marketplace backup include?
Include tenant and user references, listings, orders, versions, idempotency decisions, provider-event identities and safe fingerprints, notification attempts, retention facts, approved export facts, and bounded audit order. Test restore plus duplicate replay in an isolated environment.
Build the bounded first workflow
Turn Your Marketplace Contract into a Working App
Describe the buyers, sellers, listings, moderation, orders, provider boundary, failures, and recovery path. Start with fictional data and prove one complete lifecycle before adding more surface.
Build My Marketplace AppNo credit card required. AI credits included to start.