Arcadier’s marketplace architecture is built around a set of persistent core entities. Each entity represents a structured data object that can be created, retrieved, updated, and transitioned via API.
The platform follows an entity-driven, role-controlled, and state-based architecture. Marketplace behaviour is derived from how these entities relate to one another and how their states evolve during user interactions.
Users and identity
Every actor in the marketplace is a User. Role assignment determines access and capability:
- Admins: Configure the marketplace and have read access across all entities
- Merchants: Own Items and receive Orders
- Buyers: Initiate Cart sessions and generate Invoices
A User may hold multiple Addresses, i.e. reusable location records shared across profile, checkout, and (in Spacetime deployments) item listings.
Items and catalogue structure
Items are owned by merchant Users and represent the sell-able unit of the marketplace:
- Each Item belongs to one or more Categories, which form the hierarchical taxonomy driving browse, search, and filter experiences
- Items support variants, media, custom fields, and shipping methods
- In Spacetime deployments, Items carry additional scheduling and location data
- Child items, i.e. the specific variant records, have their own GUIDs and are the unit referenced at cart level
The order entities
The transactional layer is made up of four related entities, each with a distinct scope:
| Entity | Scope | Key behaviour |
| Cart | Pre-checkout | One record per item–variant–shipping combination. Persists across sessions for authenticated users. |
| Invoice | Checkout session | One per checkout. Buyer-facing record. References all underlying Orders. |
| Order | Per-merchant fulfillment | One per merchant within an Invoice. Fulfillment status tracked independently per seller. |
| Transaction | Payment & settlement | One per merchant Order, plus one for admin commission in standard gateway integrations. |
Extensibility
Custom Fields and Custom Tables extend core entities without modifying the base schema:
- Custom Fields: Attach structured metadata to individual entity records (e.g. vehicle compatibility on an Item, business registration on a User)
- Custom Tables: Support relational, multi-record data at the plug-in level, where a single entity record can have many associated table rows
Understanding Custom Fields & Tables
Custom Fields act as the extensibility layer for adding additional structured data to entities on the platform. It allows marketplace admins to extend the schema of key entities without modifying core platform structure. They are essential for building vertical-specific data models while keeping the integration upgrade-friendly.
Input Types:
- Text Field
- Hyperlink
- Location
- Percentage
- Number
- Checkout
- Dropdown
- Date/Time Picker
Reference Tables for Custom Fields:
- Items
- Users
- Orders
- Payments
- Cart Items
- Categories
- Panels
- Panel Details
- Developer Packages (do not use)
- Implementations
Where Custom Fields can be attached
Custom Fields support multiple reference tables (entities). Common reference tables include Items, Users, Orders, Payments, Cart Items, and Categories. Choose the reference table based on where the data must live and how it will be read during flows. Some of the ways custom fields can be used across different entities are:
- Users: Use when data is identity/profile-related and needed across sessions.
- Examples - B2B registration attributes, verification status, segmentation fields.
- Items: Use when data is listing-related and must be visible for discovery or downstream operational rules.
- Examples - Technical specs, service duration settings, compliance flags.
- Orders: Use when data is transactional/workflow-related and must be immutable once purchased (or audited).
- Examples - PO numbers, delivery instructions, approval checkpoints.
Custom Tables
Use Custom Tables when you need relational or repeated datasets beyond single-field extension (for example, multi-row structured metadata). Model Custom Tables as domain objects that can be referenced by your integration and synced alongside core entities.