Sellers: data model and onboarding

The problem#

Seller onboarding looks like a form, but it settles three separate questions: who you admit to selling at all, which data you keep and which stays with the payment provider, and at what point a seller is operationally ready.

Conflating them usually ends the same way: the account exists, products are listed, and at the first sale it turns out the money cannot be paid out, or nobody knows who is party to the contract with the buyer.

Minimum version#

A seller needs an explicit state rather than a scattering of flags. The smallest sensible set is five states and one distinction.

Operational readiness is derived from several conditions rather than a field an operator sets by hand. Four usually suffice: company details, provider verification, shipping configured and at least one product. You can compute it on read or recalculate and store it after every change. What matters is that nobody sets it manually, because then it stops describing reality.

What not to build yet#

• Your own identity verification. A marketplace payment provider already runs it and carries the responsibility.
• A multi-stage appeals system. A rejection reason and a contact address are enough to start.
• Legal entity migration for sellers. It is rare; handle it by hand the first time it happens.
• An elaborate permission matrix. Account owner and team member are enough until somebody reports a real need.

Plan ahead#

A reference to the provider account, not a copy of the data#

The platform keeps the provider account identifier and its own reading of that account status. It does not copy identity documents or bank details. Duplicating them widens your exposure without reducing the number of problems.

Data you will ask for later#

A requirement you did not think of always appears. The seller data model has to take a new field without migrating existing accounts, and the process has to be able to ask for it and hold back part of the functionality until it arrives.

Historical data apart from the profile#

A seller profile changes. The company name shown on an order from a year ago should stay as it was then. Same pattern as a price snapshot, applied to identity.

Triggers#

• the first seller asks to add a second person to the account;
• the first data erasure request;
• the first change of legal form or company name after a sale;
• approving applications starts taking more time than other operational work;
• a second person begins approving sellers.

Next stage#

After the first trigger: account roles and invitations. After the fourth: an application queue with filters and a record of who decided. A central staff activity log only once you need to reconstruct who did what across several people.

Common mistakes#

What works in practice#

In production, seller readiness on my side is derived from several independent conditions and recalculated after every change to the profile, the products, the shipping setup or the provider status. The seller then sees exactly what is missing, and the operator ticks nothing off by hand.

The second thing that mattered more than it looked at the start was separating anonymisation from deletion. An erasure request arrives sooner or later, and without that split it collides with document retention duties.

Checklist#

• Seller state is explicit and drawn from a finite list.
• Operator approval and the ability to receive money are independent conditions.
• Operational readiness is derived from conditions rather than set by hand.
• The platform keeps a reference to the provider account, not a copy of its data.
• Seller details shown on an order are recorded at the time of sale.
• Anonymisation is separate from deleting settlement records.