Test

opis

Add Epic JSON File
JSON file should contain an epic with user stories and acceptance criteria.

Epics in Project (15)

Crating initialization of system

ID Name Description Acceptance Criteria Notes Actions
US-01 Create Agnet.MD Create agnet md for .net developer with ASP.Net on forontend
  • Chceck is it properly added to the system.
US-02 Create prd.md Create prd.md files for the scope of the application; these will be updated during the project. It will be a system for selling products added by multiple sellers. As a buyer, I would want to buy many products by adding them to a cart, adding a shipping address, and paying for them.
IAM-03 Support social login for buyers As a buyer I want to log in or register using my Google or Facebook account so that I can quickly access Mercato without creating a new password.
  • Given I am an unauthenticated visitor when I open the login/registration page then I see options to continue with Google and Facebook.
  • Given I choose to continue with Google or Facebook and successfully authorize Mercato when my email is not yet used on the platform then a buyer account is created and I am logged in.
  • Given I choose to continue with Google or Facebook and successfully authorize Mercato when my email already exists as a buyer on the platform then I am logged in to that existing account.
  • Given a social login attempt fails due to provider error or denied consent when I return to Mercato then I see a clear error message and remain unauthenticated.
  • Social login is available only for buyers in the initial scope.
  • Implementation must follow providers' latest OAuth/OIDC guidelines.
  • Apple login should be supported later without redesigning the current SSO abstraction.
IAM-04 Verify seller email and support optional KYC As a seller I want my email to be verified and optionally complete KYC so that buyers and the platform can trust my identity.
  • Given I register as a seller when my account is created then the system generates a unique, time-limited email verification link and sends it to my email address.
  • Given I receive a verification email when I click the link within its validity period then my email status is updated to 'verified' and I can access the seller panel.
  • Given my verification link expired or was already used when I click it then I see an error and an option to request a new verification email.
  • Given KYC is required when I log in as a seller without completed KYC then I am guided through a KYC flow and my access to certain features is restricted until KYC is approved.
  • KYC provider integration details defined later.
  • Email verification required for sellers.
  • Store verification and KYC audit data.
IAM-05 Reset and change password securely As a user I want to reset a forgotten password and change my password so that I can maintain secure access to my account.
  • Given I forgot my password when I request a reset then the system sends a time-limited password reset link without revealing whether the email exists.
  • Given I receive a valid reset link when I provide a new password then my password is updated and all active sessions are invalidated.
  • Given a reset link is expired or invalid when I try to open it then I see an error and a way to request a new link.
  • Given I am logged in when I provide my current and new password then my password is updated.
  • Reset tokens must be single-use.
  • Do not leak whether email exists.
  • Keep design flexible for password policy updates.
IAM-06 Manage user sessions with secure tokens As the system I want to manage user sessions with secure tokens so that authenticated access is controlled.
  • Given a user logs in when a session is created then the system issues a secure token.
  • Given a session token exists when requests are made then the system validates it.
  • Given session lifetime is exceeded when user performs an action then re-authentication is required.
  • Given a user logs out when logout is processed then the session is invalidated.
  • Protect tokens from XSS and CSRF.
  • Session store must support horizontal scaling.
  • Future 2FA must fit the design.
IAM-07 Role-based access control As the platform owner I want buyer, seller and admin roles enforced so that each user can access only allowed features.
  • Buyers access only buyer features.
  • Sellers access only their seller panel.
  • Admins access admin panel only.
  • Unauthorized access attempts return a clear error.
  • Role model must be extensible.
  • Central authorization checks required.
  • Authorization failures logged.
IAM-08 Account security baseline with 2FA readiness As the platform owner I want an account security baseline with 2FA readiness and login history so that the platform can improve security later.
  • Account model supports 2FA configuration.
  • Login events can be logged.
  • 2FA can be enabled without breaking flows.
  • Unusual login activity can trigger alerts.
  • 2FA not part of MVP.
  • Login history must follow retention rules.
  • Security events must be auditable.
Send to GitHub

Core identity and access management for buyers, sellers and admins including registration, authentication, role-based access and a security baseline for the Mercato marketplace.

ID Name Description Acceptance Criteria Notes Actions
IAM-01 Register buyer and seller accounts with email and password As a visitor I want to create a buyer or seller account with email and password so that I can access marketplace features appropriate for my role.
  • Given I am an unauthenticated visitor when I open the registration form then I can choose whether to register as a buyer or as a seller.
  • Given I am on the registration form when I provide required data and a valid password and accept terms then my account is created in status 'unverified'.
  • Given my account is created when the system sends a verification email then I see an information message that I must verify my email before full access.
  • Given I submit the registration form with missing or invalid data when I try to submit then I see clear validation errors and my data is not persisted.
  • Registration must capture minimum required personal and legal data for later KYC and invoicing.
  • Passwords must follow security policy (length, complexity, no common passwords).
  • Email address must be unique across all users.
IAM-02 Authenticate buyers and sellers with email and password As a registered user I want to log in with my email and password so that I can securely access buyer or seller features.
  • Given I am a registered user with a verified email when I enter correct email and password then I am successfully logged in and redirected to the appropriate dashboard for my role.
  • Given I am a registered user when I enter an incorrect email or password then I see a generic error message and I am not logged in.
  • Given I am a seller with an unverified email when I attempt to log in then I see a clear message that I must verify my email and I receive a link to resend the verification email.
  • Given I am logged in when I close the browser and reopen it within the configured session lifetime then my session is still valid and I remain authenticated unless I explicitly logged out before.
  • Use secure password hashing and never store plain text passwords.
  • Login must be rate limited and monitored to reduce brute-force risk.
  • Future 2FA must be pluggable into this login flow without breaking existing contracts.
IAM-03 Support social login for buyers As a buyer I want to log in or register using my Google or Facebook account so that I can quickly access Mercato without creating a new password.
  • Given I am an unauthenticated visitor when I open the login/registration page then I see options to continue with Google and Facebook.
  • Given I choose to continue with Google or Facebook and successfully authorize Mercato when my email is not yet used on the platform then a buyer account is created and I am logged in.
  • Given I choose to continue with Google or Facebook and successfully authorize Mercato when my email already exists as a buyer on the platform then I am logged in to that existing account.
  • Given a social login attempt fails due to provider error or denied consent when I return to Mercato then I see a clear error message and remain unauthenticated.
  • Social login is available only for buyers in the initial scope.
  • Implementation must follow providers' latest OAuth/OIDC guidelines.
  • Apple login should be supported later without redesigning the current SSO abstraction.
IAM-04 Verify seller email and support optional KYC As a seller I want my email to be verified and optionally complete KYC so that buyers and the platform can trust my identity.
  • Given I register as a seller when my account is created then the system generates a unique, time-limited email verification link and sends it to my email address.
  • Given I receive a verification email when I click the link within its validity period then my email status is updated to 'verified' and I can access the seller panel.
  • Given my verification link expired or was already used when I click it then I see an error and an option to request a new verification email.
  • Given KYC is required when I log in as a seller without completed KYC then I am guided through a KYC flow and my access to certain features is restricted until KYC is approved.
  • KYC provider integration details defined later.
  • Email verification required for sellers.
  • Store verification and KYC audit data.
IAM-05 Reset and change password securely As a user I want to reset a forgotten password and change my password so that I can maintain secure access to my account.
  • Given I forgot my password when I request a reset then the system sends a time-limited password reset link without revealing whether the email exists.
  • Given I receive a valid reset link when I provide a new password then my password is updated and all active sessions are invalidated.
  • Given a reset link is expired or invalid when I try to open it then I see an error and a way to request a new link.
  • Given I am logged in when I provide my current and new password then my password is updated.
  • Reset tokens must be single-use.
  • Do not leak whether email exists.
  • Keep design flexible for password policy updates.
IAM-06 Manage user sessions with secure tokens As the system I want to manage user sessions with secure tokens so that authenticated access is controlled.
  • Given a user logs in when a session is created then the system issues a secure token.
  • Given a session token exists when requests are made then the system validates it.
  • Given session lifetime is exceeded when user performs an action then re-authentication is required.
  • Given a user logs out when logout is processed then the session is invalidated.
  • Protect tokens from XSS and CSRF.
  • Session store must support horizontal scaling.
  • Future 2FA must fit the design.
IAM-07 Role-based access control As the platform owner I want buyer, seller and admin roles enforced so that each user can access only allowed features.
  • Buyers access only buyer features.
  • Sellers access only their seller panel.
  • Admins access admin panel only.
  • Unauthorized access attempts return a clear error.
  • Role model must be extensible.
  • Central authorization checks required.
  • Authorization failures logged.
IAM-08 Account security baseline with 2FA readiness As the platform owner I want an account security baseline with 2FA readiness and login history so that the platform can improve security later.
  • Account model supports 2FA configuration.
  • Login events can be logged.
  • 2FA can be enabled without breaking flows.
  • Unusual login activity can trigger alerts.
  • 2FA not part of MVP.
  • Login history must follow retention rules.
  • Security events must be auditable.
Send to GitHub

Enable sellers to onboard, configure and verify their store, expose a public store page, define payout settings, and (in Phase 2) manage internal seller users.

ID Name Description Acceptance Criteria Notes Actions
US-01 Seller onboarding wizard As a seller I want to be guided by an onboarding wizard so that I can quickly create my store account and complete the minimum required setup.
  • Given I am a new seller without a store on the platform, when I start the seller onboarding, then I am guided through a multi-step wizard.
  • Given I am in the onboarding wizard, when I provide all mandatory fields in a step, then I can move to the next step and my progress is saved.
  • Given I have partially completed the onboarding wizard, when I log out and log back in, then I can resume onboarding from the last completed step.
  • Given I have completed all required steps in the onboarding wizard, when I submit the wizard, then my seller account and initial store profile are created and activated in a pending verification state.
  • Wizard steps should at minimum cover store profile basics, verification data and payout basics.
  • Support for saving draft data between steps is required.
  • Error messages must explain which fields are missing or incorrect.
US-02 Manage store profile As a seller I want to manage my store profile so that buyers see clear and accurate information about my store.
  • Given I am an authenticated seller, when I open my store settings, then I can view and edit store name, logo, description and contact details.
  • Given I upload a store logo that meets format and size requirements, when I save the profile, then the new logo is stored and displayed on my public store page.
  • Given I edit my store profile fields correctly, when I save changes, then the updated data is immediately visible in my seller panel.
  • Given my store profile is saved, when a buyer opens my public store page, then the name, logo, description and contact information are displayed according to the configured profile.
  • Contact details should at least support email address and optional phone number and website URL.
  • Store name must be unique across all stores on the platform or validated according to business rules.
  • Profile changes may be subject to moderation in other epics if required by compliance rules.
US-03 Fill verification form As a seller I want to fill a verification form so that the marketplace can verify my identity or company details before fully activating my store.
  • Given I am an authenticated seller, when I open the verification section, then I see a form adapted to my seller type (company or individual).
  • Given I am a company seller, when I fill in company name, registration number, tax ID, registered address and contact person, then the form validates required fields and formats before I can submit.
  • Given I am an individual seller, when I provide my full name, personal ID number or equivalent, address and contact details, then the form validates required fields and formats before I can submit.
  • Given I have completed the verification form with valid data, when I submit it, then my verification status is updated to 'Pending review' and the data is stored for back-office processing.
  • Given my verification status is 'Pending review', when I view the verification section, then I see the current status and cannot submit a new application until the status changes or I am explicitly allowed to update data.
  • Exact list of required fields for company and individual sellers must follow legal and compliance requirements in target markets.
  • Verification review workflow and manual checks may be handled in a separate epic for back-office operations.
  • Sensitive personal and company data must be stored and processed in line with GDPR and internal security standards.
US-04 Public store page As a buyer I want to see a public store page so that I can learn more about the seller before making a purchase.
  • Given a store is at least in an active or limited-active state according to business rules, when I open its public URL, then I see the store name, logo, description and basic contact information.
  • Given I open a public store page, when the store has products listed, then I see a list or preview of products with the ability to navigate to full product listings.
  • Given a store is suspended or not yet verified for public display, when I try to open its public URL, then I see an appropriate message or the page is not accessible according to business rules.
  • Given a seller updates their store profile, when I refresh the public store page, then I see the latest published version of the profile data.
  • Public store URL pattern should be stable and SEO-friendly, for example /store/{storeSlug}.
  • Visibility rules for unverified or suspended stores must be clearly defined with the business.
  • Product listing behaviour on the store page (sorting, pagination, filters) may be detailed in product/catalog related epics.
US-05 Configure bank account and payout preferences As a seller I want to configure my bank account and payout preferences so that I can receive funds from sales on the marketplace.
  • Given I am an authenticated seller, when I open the payout settings section, then I can provide required bank account details or supported payout methods for my region.
  • Given I enter bank account details in the required format, when I save the configuration, then the system validates the data and stores it securely.
  • Given I have one or more valid payout methods configured, when I choose a default payout method, then future payouts use this method unless I change it.
  • Given my payout settings are incomplete or invalid, when I attempt to complete onboarding or receive a payout, then the system informs me that payout configuration must be fixed before transfers can be processed.
  • Given I change my payout preferences, when I save them successfully, then the changes are reflected on my payout settings screen and used for subsequent payout operations.
  • Exact payout options depend on integrated payment provider capabilities (e.g. bank transfer, payout to payment account).
  • Bank account data and other payout credentials must be encrypted at rest and protected in transit.
  • Changes to payout settings may require additional verification (e.g. two-factor authentication or manual review) to prevent fraud.
US-06 Seller internal user management (Phase 2) As a store owner I want to manage internal users and their roles so that my team members can work in the seller panel with appropriate permissions.
  • Given I am a store owner, when I open the user management section, then I can see a list of internal users associated with my store including their roles and status.
  • Given I am a store owner, when I invite a new internal user by email and assign a role, then the system sends an invitation and creates a pending user record.
  • Given an invited internal user receives an invitation, when they accept the invitation and complete registration, then they gain access to the seller panel with the assigned role.
  • Given I am a store owner, when I change the role of an existing internal user, then their permissions in the seller panel are updated accordingly on their next action or session.
  • Given I am a store owner, when I deactivate an internal user, then that user can no longer sign in to the seller panel for my store and any active sessions are invalidated.
  • At minimum define roles such as StoreOwner (full access), CatalogManager (product management), OrderManager (order processing) and ReadOnly/Accounting (report access).
  • Role and permission model should reuse or extend the global identity and access management epic.
  • This functionality is explicitly planned for Phase 2 and must be feature-flagged or time-gated, not blocking MVP store activation.
Send to GitHub

Enable sellers and admins to manage the product catalog for the Mercato marketplace, including product CRUD, categories, imports/exports, bulk updates, workflow and images.

ID Name Description Acceptance Criteria Notes Actions
US-01 Create product in seller panel As a seller I want to create a new product in my catalog so that I can offer it for sale on the marketplace.
  • Given I am logged in as a seller and I have access to my seller panel, when I open the 'Add product' form and fill all required fields, then a new product record is created and stored in the system.
  • Given I submit the 'Add product' form with missing or invalid required fields, when I try to save the product, then the system shows clear validation errors and prevents saving until issues are fixed.
  • Given I successfully create a product, when I return to the product list, then I can see the product with status 'draft' by default.
  • Required fields should include at minimum: title, price, stock, category.
  • New products should default to workflow state 'draft' and not be visible in the public catalog until activated.
  • Access restricted to seller accounts; admins may have separate tools for moderation.
US-02 Edit and delete product in seller panel As a seller I want to edit and delete my existing products so that I can keep my catalog accurate and remove products I no longer sell.
  • Given I am logged in as a seller and I own a product, when I open the product edit form and change its data, then the updated product details are saved and visible in my product list.
  • Given I try to edit a product that I do not own, when I open the product details, then I cannot access the edit form and receive an authorization error.
  • Given I am logged in as a seller and I own a product, when I choose to delete the product, then the system either soft-deletes or archives it and it no longer appears in search results or public listings.
  • Given a product is deleted or archived, when a buyer tries to access it via direct link, then the system returns a clear message that the product is unavailable.
  • Deletion strategy should prefer soft-delete or 'archived' workflow state for audit and reporting.
  • Changes to price or stock may affect orders; validate business rules around products linked to active or past orders.
  • All edits should be logged for audit purposes (who changed what and when).
US-03 Manage product attributes As a seller I want to manage core product attributes like title, description, images, price, stock, category and shipping parameters so that buyers see correct and complete product information.
  • Given I am editing a product, when I update its title and description, then the new texts are stored and displayed on the product detail page.
  • Given I am editing a product, when I change its price and stock, then the new values are used in buyer-facing views and checkout.
  • Given I assign or change a category for a product, when I save the product, then it is visible under the selected category in the buyer catalog.
  • Given I edit shipping parameters (e.g. weight, dimensions, shipping methods), when I save the product, then these parameters are available for shipping cost calculation and logistics flows.
  • Price and stock have to follow configured validation rules (e.g. non-negative, max limits).
  • Category must reference an existing node in the category tree managed by admin.
  • Shipping parameters should be aligned with later logistics integrations (e.g. couriers, parcel lockers).
US-04 Manage category tree as admin As an admin I want to manage the global product category tree so that products can be consistently organized and easily discoverable.
  • Given I am logged in as an admin, when I open the category management view, then I can see the current category tree with parent-child relationships.
  • Given I am in the category management view, when I create a new category (with name and optional parent), then it appears in the tree and becomes available for sellers to assign to products.
  • Given I am in the category management view, when I rename or reorder categories, then changes are reflected for all new and existing products that use those categories.
  • Given I try to delete a category that has assigned products, when I confirm deletion, then the system either prevents deletion with a clear message or forces re-assignment of products according to a defined rule.
  • Category tree should support multiple levels (e.g. category, subcategory).
  • Changes in category structure must not break existing product links or search.
  • Consider supporting category activation/deactivation instead of hard deletion.
US-05 Product workflow management As a seller I want to manage the workflow state of my products (draft, active, suspended, archived) so that I control which products are visible and sellable.
  • Given a product is in 'draft' state, when I set it to 'active' and all required data is valid, then it becomes visible and searchable for buyers in the marketplace.
  • Given a product is in 'active' state, when I change its state to 'suspended', then it is no longer available for new orders but remains visible only where business rules allow (e.g. in order history).
  • Given a product is in any state, when I set it to 'archived', then it is completely removed from public listings and normal seller editing flows, but remains available for reporting and audit.
  • Given required fields are missing or invalid, when I try to set state to 'active', then the system blocks the transition and informs me which fields must be fixed.
  • Workflow transitions should be validated; not all transitions must be allowed (e.g. active -> draft may be restricted).
  • Active products must meet minimum data quality rules (images, description, category, price, stock).
  • Admins should be able to override states (e.g. suspend a product for policy violations).
US-06 Bulk update price and stock As a seller I want to bulk update price and stock for multiple products so that I can quickly reflect changes in my catalog without editing each product separately.
  • Given I am logged in as a seller and I select multiple products in my product list, when I apply a bulk change to price (e.g. fixed value, percentage up/down), then the system updates prices for all selected products and shows a confirmation.
  • Given I select multiple products and apply a bulk change to stock (e.g. set exact value, increase, decrease), when I confirm the operation, then all selected products' stock levels are updated accordingly.
  • Given I configure a bulk update, when the operation would lead to invalid values (e.g. negative price or stock), then the system prevents the update and informs me which products failed and why.
  • Given a bulk update finishes successfully, when I refresh my catalog view or export data, then I see the new values reflected.
  • Bulk operations should be safe and possibly executed as background jobs for large sets.
  • Provide preview or summary of the impact before the seller confirms the bulk update.
  • Log bulk update operations for audit and rollback analysis.
US-07 Import product catalog via CSV/XLS As a seller I want to import my product catalog from a CSV/XLS file so that I can quickly onboard or update many products at once.
  • Given I am logged in as a seller, when I upload a CSV/XLS file that matches the required template, then the system validates the file and provides a summary of how many products will be created and updated.
  • Given the uploaded file contains validation errors (e.g. missing required fields, invalid categories, wrong data types), when the system processes it, then it reports errors per row and does not import invalid records.
  • Given the uploaded file passes validation, when I confirm the import, then the system creates new products and updates existing products according to a defined matching rule (e.g. by SKU or internal product ID).
  • Given an import job is running in the background, when I open the import history screen, then I can see the status, statistics (successes, failures) and download an error report if any rows failed.
  • Define a clear mapping/template for CSV/XLS columns (title, description, price, stock, category, shipping parameters, SKU, etc.).
  • Import should support idempotent updates using a stable key (e.g. merchant SKU).
  • Large files should be processed asynchronously with progress and error reporting.
US-08 Export product catalog for reporting As a seller I want to export my product catalog to CSV/XLS so that I can analyze or process product data in external tools.
  • Given I am logged in as a seller, when I open the export function and select export format (CSV/XLS), then the system generates a file with all my products and their key attributes.
  • Given I filter or search in my product list, when I trigger the export, then the generated file reflects the current filter (only matching products are exported) if I choose that option.
  • Given the export completes, when I download the file, then the columns are labeled clearly and data is consistent with the latest state of the catalog.
  • Export should respect seller boundaries; a seller can export only their own products.
  • For large catalogs, export should be processed as a background job with a downloadable link.
  • Export format should align with import format as much as possible to support round-trip editing.
US-09 Upload and manage product images As a seller I want to upload and manage product images so that my products are visually attractive and meet platform quality standards.
  • Given I am creating or editing a product, when I upload one or more image files in supported formats, then the system stores them and shows thumbnails in the product form.
  • Given an image exceeds maximum size or uses an unsupported format, when I try to upload it, then the system rejects it with a clear validation message.
  • Given I uploaded at least one image, when I mark one as the main image, then this image is used as the primary thumbnail in product listings and search results.
  • Given images are stored, when the system processes them, then optimized versions (e.g. resized, compressed) are generated for different display contexts without degrading quality excessively.
  • Define allowed formats (e.g. JPG, PNG, WebP) and size limits for uploads.
  • Image optimization should include resizing, compression and possibly format conversion for web performance.
  • Consider using a CDN or cloud storage for serving product images efficiently.
US-10 Support product variants (Phase 2) As a seller I want to define product variants (e.g. size, color) so that buyers can select the exact configuration they need under a single product listing.
  • Given I am in the product edit view and the variants feature is enabled, when I define variant attributes (e.g. size, color) and their values, then the system creates variant combinations with separate stock and price per variant where applicable.
  • Given a product has variants, when a buyer views the product page, then they can select variant options (e.g. size, color) and the correct price, stock and images for the chosen variant are displayed.
  • Given a variant is out of stock, when a buyer selects that variant, then the system prevents adding it to the cart and shows that the variant is unavailable.
  • This story is explicitly planned for Phase 2; do not block MVP on its implementation.
  • Data model should be designed in a way that allows adding variants later without breaking existing simple products.
  • Variants may have their own SKU, stock and possibly separate images.
Send to GitHub

Enable buyers to efficiently discover and navigate products across the marketplace using categories, search, filters, sorting, and navigation helpers.

ID Name Description Acceptance Criteria Notes Actions
US-04-01 Browse products by category As a buyer I want to browse products via category listing pages so that I can easily discover products in areas I am interested in.
  • Given that categories are configured in the system, when I open a category listing page, then I see a list of products assigned to that category.
  • Given that a category has subcategories, when I open the parent category page, then I can navigate to its subcategories and optionally see products aggregated or scoped according to UX design.
  • Given that a category has no products, when I open that category page, then I see an empty state message and suggestions to navigate to other categories or search.
  • Given I am on a category listing page, when I navigate to another category, then the product list refreshes to show products for the newly selected category.
  • Category tree is managed in the admin and reused from catalog domain.
  • SEO-friendly URLs for category pages are desirable but can be refined later.
  • Large categories may require pagination or infinite scroll behavior shared with search results.
US-04-02 Global keyword search As a buyer I want to search products using keywords so that I can quickly find specific products without browsing through all categories.
  • Given I am on any page with the global search bar visible, when I type a keyword and submit the search, then I am redirected to a search results page showing matching products.
  • Given there are products that match my search term, when results are displayed, then I see product title, price, thumbnail image, and other key attributes as defined by UX.
  • Given there are no products matching my search term, when results are displayed, then I see an informational message and suggestions to adjust my query or browse categories.
  • Given my search query is long or contains special characters, when I submit it, then the system handles it safely and either returns results or a clear message without errors.
  • Initial implementation can use simple keyword matching on title and description; advanced relevance tuning can follow later.
  • Search must only return active, non-archived, non-suspended products.
  • Search results page shares common components with category listing pages (grid layout, filters, sorting, pagination).
US-04-03 Filter search and category results As a buyer I want to filter product lists by category, price, condition, and seller so that I can narrow results to products that match my preferences.
  • Given I am on a search or category results page, when I open the filter panel, then I can see filters for category, price range, condition, and seller.
  • Given I select one or more filter values, when I apply filters, then the results list updates to show only products that match all selected filter criteria.
  • Given I have active filters, when I clear all filters with a single action, then all selected filters are removed and the full unfiltered result set for the current query or category is shown.
  • Given I have applied filters, when I refresh or navigate back to the results page within the same session, then my filters remain applied until I explicitly change or clear them.
  • Given a selected filter results in zero matching products, when I apply it, then I see an empty state message and a clear indication of active filters with an option to reset them.
  • Filters must be compatible with both search results and category listing views.
  • Price filter should support at least min and max values; UX may choose slider or numeric inputs.
  • Condition and seller filter values must be based on data model from product and seller domains.
  • Filtering performance must remain acceptable for large result sets; indexing strategy may be required.
US-04-04 Sort product results As a buyer I want to sort product results by relevance, price, and newest so that I can quickly view products in the order that matters most to me.
  • Given I am on a search or category results page, when I open the sort control, then I can choose at least relevance, price ascending, price descending, and newest.
  • Given I select a sort option, when the results refresh, then products are ordered according to the selected criteria.
  • Given I change my sort option, when the results update, then my currently applied filters and search query remain unchanged.
  • Given I first land on a search results page, when I have not chosen any sort option, then a default sort (e.g. relevance or newest) is applied and visibly indicated.
  • Given I have selected a sort option, when I navigate to the next or previous page (or infinite scroll segment), then the same sort order is preserved.
  • Default sort strategy should be defined globally (e.g. relevance for search, newest for pure category browsing).
  • Sorting must be consistent and stable for the same query and dataset.
  • Complex ranking rules (sponsored listings, personalization) are out of scope for MVP.
US-04-05 Paginate or infinitely scroll results As a buyer I want product results to be split into pages or loaded as I scroll so that I can browse large result sets without performance issues.
  • Given a search or category results page with more products than the configured per-page limit, when I open the page, then I see the first batch of results and a clear way to access more results (pagination controls or infinite scroll).
  • Given pagination is used, when I click a specific page number or next/previous control, then the corresponding results page loads and the current page is highlighted.
  • Given infinite scroll is used, when I scroll near the bottom of the current results list, then the next batch of results loads without losing the already displayed items.
  • Given I refresh the results page or navigate back to it during the same session, when pagination state is preserved, then I return to the same page of results or scroll position as before, according to UX decision.
  • Given there are no more results to load, when I reach the end of paginated or infinite scroll content, then I see a clear indication that all results have been displayed.
  • Choose either classic pagination or infinite scroll for MVP; implementation should be extensible to support the other pattern later if needed.
  • URL structure should support deep-linking to a specific page or state where feasible.
  • Result loading must be optimized to avoid long response times on large result sets.
US-04-06 Show search suggestions (Phase 2) As a buyer I want to see search suggestions while typing so that I can quickly complete my query or discover relevant categories and products without typing the full term.
  • Given I am focused in the global search input, when I start typing at least the configured minimum number of characters, then I see a dropdown with suggestions such as popular queries, matching categories, or products.
  • Given suggestions are displayed, when I click on a suggested query, then the search input is populated with that query and the full search is executed.
  • Given suggestions are displayed, when I click on a suggested category, then I am redirected to that category listing page.
  • Given I continue typing or delete characters, when my input changes, then the suggestion list is updated in near real time or hidden if there are no suggestions.
  • Given there are no suggestions for my input, when I type, then the suggestion dropdown is hidden or shows an appropriate message without blocking manual search.
  • This story is explicitly planned for Phase 2 and is not required for initial MVP.
  • Rate limiting and debouncing should be applied to suggestion queries to avoid performance issues.
  • Suggestion ranking strategy (popularity, relevance, personalization) can be iteratively improved.
US-04-07 Recently viewed products As a buyer I want to see a list of my recently viewed products so that I can easily return to items I considered earlier without searching again.
  • Given I view a product detail page, when I navigate to another page, then the viewed product is added to my recently viewed list for the current device/session.
  • Given I have viewed multiple products, when I open a page that displays recently viewed items (e.g. home page, product page sidebar), then I see a list ordered from most recently viewed to oldest, limited to the configured maximum number of items.
  • Given the same product is viewed multiple times, when the recently viewed list is updated, then the product appears only once and is moved to the most recent position.
  • Given I clear my browser cookies or explicitly clear my recently viewed list (if UX provides such option), when I revisit the page, then the recently viewed section is empty until I view new products.
  • Given I am a logged-in buyer and I use multiple devices, when cross-device synchronization is not yet implemented, then recently viewed products are tracked per device/session according to MVP scope.
  • Initial implementation can store recently viewed items client-side (e.g. cookies or local storage); optional server-side tracking can be added later for logged-in users.
  • Placement of the recently viewed section (home, product details, cart) should be agreed with UX.
  • Ensure only active, visible products are shown; handle gracefully when a previously viewed product is no longer available.
US-04-08 Consistent navigation between search, category, and product pages As a buyer I want consistent navigation between search, category lists, and product detail pages so that I do not get lost when exploring the marketplace.
  • Given I arrive on a product detail page from a search or category results list, when I use the browser back button or a dedicated "Back to results" action, then I return to the same results view with previously applied filters, sort order, and position.
  • Given I am on a product detail page, when I click on the product’s category link, then I am redirected to the corresponding category listing page.
  • Given I am on a product detail page, when I click on the seller link, then I am redirected to the seller’s public store page in the buyer portal.
  • Given I am on any page, when I use the main navigation (logo, main menu, search bar), then I can always reach the home page, category overview, and global search without dead ends or inconsistent behaviors.
  • Behavior for browser back navigation should be validated across major browsers and mobile devices.
  • Deep-linking from marketing campaigns to search or category pages must respect the same navigation patterns.
  • This story ties together several UX behaviors and may be implemented incrementally as other stories are delivered.
Send to GitHub

Enable buyers to manage a multi-seller cart and complete a secure checkout flow including address, shipping, payment, and order confirmation.

ID Name Description Acceptance Criteria Notes Actions
US-01 Add items from multiple sellers to cart As a buyer I want to add products from different sellers to a single cart so that I can place one combined order instead of multiple separate purchases.
  • Given I am browsing products from various sellers when I click 'Add to cart' on any product then the item is added to my cart without removing items from other sellers.
  • Given my cart contains items from multiple sellers when I open the cart then items are grouped or clearly labeled by seller.
  • Given an item is already in my cart when I add the same product again then the system either increases the quantity or informs me that the item is already in the cart according to business rules.
  • Cart must support products from multiple sellers within a single session.
  • Cart data structure should allow splitting the order into sub-orders per seller at checkout.
  • Ensure cart UX clearly indicates which seller owns each item.
US-02 Edit quantity and remove items from cart As a buyer I want to change quantities and remove items from my cart so that I can finalize exactly what I intend to purchase.
  • Given I am on the cart page when I change the quantity of an item then the cart updates the quantity and recalculates totals immediately.
  • Given I am on the cart page when I set the quantity of an item to zero or click 'Remove' then the item is removed from the cart.
  • Given I remove the last item from my cart when the cart is empty then I see an 'empty cart' state and no totals or checkout button are displayed.
  • Validate quantity values (minimum 1, maximum based on available stock).
  • Recalculate totals on each quantity change or item removal.
  • Handle edge cases where stock has changed since the item was added.
US-03 Calculate cart totals with shipping and commissions As a buyer I want to see clear cart totals including shipping so that I understand the full cost before I place my order.
  • Given my cart contains items from one or more sellers when I open the cart then I see item subtotal, shipping costs, and total amount payable.
  • Given shipping rules per seller are configured when I change quantities or remove items then shipping and total amounts are recalculated according to the updated cart contents.
  • Given internal commission rules exist when the platform calculates seller payouts then commissions are not visible to the buyer and are applied only in internal financial calculations.
  • Support per-seller shipping rules and aggregate them into a single total for the buyer.
  • Commission calculation must be consistent with the central payments/settlements model.
  • Totals logic should be reusable by the checkout and order modules.
US-04 Persist guest cart and merge after login As a buyer I want my guest cart to be preserved and merged with my account cart after login so that I do not lose selected items when I sign in or register.
  • Given I am not logged in when I add items to the cart then the cart is persisted for my browser session and survives page refreshes.
  • Given I have items in my guest cart when I log in or register successfully then my guest cart is merged with my existing user cart based on defined merge rules.
  • Given the same product exists in both guest and user carts when carts are merged then the system resolves conflicts according to business rules (for example summing quantities).
  • Given my guest cart is merged into my user cart when the merge is complete then the guest cart is cleared and subsequent cart changes are associated with my user account.
  • Use a stable identifier (cookie or local storage) to persist guest cart before login.
  • Define clear merge strategy for duplicates and out-of-stock items.
  • Consider security implications when merging carts across devices or browsers.
US-05 Capture and manage delivery address during checkout As a buyer I want to provide or select a delivery address during checkout so that my order can be shipped to the correct location.
  • Given I start the checkout flow when I reach the address step then I can select an existing saved address or enter a new address.
  • Given I enter a new address and all required fields are valid when I confirm the address step then the address is saved to the order and optionally stored in my profile if I am logged in.
  • Given required address fields are missing or invalid when I try to proceed to the next step then I see validation errors and cannot continue.
  • Given my cart contains items that cannot be shipped to my region when I provide an address outside allowed regions then the system informs me and prevents completing the order.
  • Address format should support multiple countries where Mercato operates.
  • Decide whether guest checkout stores address only on the order or also in a temporary profile.
  • Prepare model to support multiple addresses per buyer in future.
US-06 Select shipping and payment methods during checkout As a buyer I want to select shipping and payment options during checkout so that I can choose the most convenient way to receive and pay for my order.
  • Given I have completed the address step when I move to the shipping step then I see available shipping methods calculated based on my address and cart contents.
  • Given shipping methods are available when I select one option per seller or for the entire order (according to business rules) then shipping cost in the order summary is updated.
  • Given the platform is integrated with an online payment provider when I reach the payment step then I can choose from supported payment methods and confirm payment redirection or widget.
  • Given the payment is successfully authorized when I return from the payment provider then the order is marked as 'payment confirmed' and the checkout flow continues to the confirmation page.
  • Shipping options may depend on seller configuration and destination.
  • Payment methods should be configured centrally and respect marketplace escrow model.
  • Handle payment failure, cancellation, and retry scenarios gracefully.
US-07 Validate stock and price before placing order As a buyer I want the system to validate stock and prices during checkout so that I do not place an order that cannot be fulfilled or has outdated pricing.
  • Given I am on the final review step of checkout when I click 'Place order' then the system re-validates stock availability for each cart item.
  • Given the stock for an item is insufficient when validation runs then I see a clear message explaining that the item or requested quantity is unavailable and the order is not created until I adjust the cart.
  • Given product prices have changed since the item was added to the cart when validation runs then I am informed about the new price and asked to confirm or update my cart before continuing.
  • Given all stock and prices are valid when validation completes then the order is created and a stable snapshot of item prices and quantities is stored with the order.
  • Stock and price checks should be executed in a transactional way to avoid race conditions.
  • Consider short reservation or locking mechanism for items at the final step.
  • Validation logic must be shared between cart and order modules for consistency.
US-08 Show order confirmation page and send email As a buyer I want to see an order confirmation page and receive a confirmation email so that I have a clear record of my purchase.
  • Given my order is successfully created and payment is confirmed when checkout is completed then I am redirected to an order confirmation page with order number and key details.
  • Given the order confirmation page is displayed when I review it then I can see items ordered, prices, shipping method, delivery address, and estimated delivery information if available.
  • Given an order has been created when checkout finishes then a confirmation email is sent to my email address with the same key information as on the confirmation page.
  • Given I am a logged-in buyer when the order is confirmed then the order appears in my order history with status reflecting the current stage.
  • Confirmation page should be accessible later via order history for logged-in buyers.
  • Email templates must be configurable and localized.
  • Ensure idempotency so duplicate emails or orders are not created if the user refreshes the confirmation page.
US-09 Apply promo codes at checkout (Phase 2) As a buyer I want to apply promo codes during checkout so that I can receive discounts on my order when eligible.
  • Given the promo engine is enabled when I am on the cart or checkout page then I can enter a promo code in a dedicated input field.
  • Given I enter a valid promo code that applies to my cart when I click 'Apply' then the discount is calculated, shown separately, and the order total is reduced accordingly.
  • Given I enter an invalid, expired, or ineligible promo code when I click 'Apply' then I see a clear error message and no discount is applied.
  • Given multiple promo codes are not allowed when a promo is already applied then the system prevents adding another promo code and informs me of the limitation.
  • Feature planned for Phase 2; do not block MVP launch if not implemented.
  • Architecture of totals and pricing should be prepared to support discount rules and stacks.
  • Promo codes may be issued by Mercato or by individual sellers; rules must support both scopes.
Send to GitHub

Handle order creation, splitting into seller sub-orders, status tracking, basic returns and fulfilment workflows for buyers and sellers.

ID Name Description Acceptance Criteria Notes Actions
US-06-01 Create order with automatic seller sub-orders As a buyer I want my cart to be converted into an order that is automatically split into seller sub-orders so that each seller can fulfil only their own part of the purchase.
  • Given a cart containing items from multiple sellers, when I confirm the checkout, then the system creates one parent order and separate sub-orders for each seller.
  • Given a cart containing items from a single seller, when I confirm the checkout, then the system creates one parent order and one sub-order for that seller.
  • Given a successfully created order and sub-orders, when I open my order details, then I can see the parent order summary and a breakdown by seller sub-orders.
  • Given seller sub-orders created from my cart, when I view the seller side, then each seller only sees the sub-orders and line items that belong to them.
  • Depends on shopping cart and checkout epics (cart contents, delivery address, shipping method, payment confirmation).
  • Parent order should hold global information (buyer, payment, totals); seller sub-orders hold seller-specific items, shipping and fulfilment data.
  • Consider idempotency: repeated callbacks from payment provider must not create duplicate orders.
US-06-02 Order status lifecycle and visibility As a buyer I want to see clear statuses for my orders and sub-orders so that I understand where my purchase is in the fulfilment process.
  • Given an order just created and awaiting payment confirmation, when payment is authorized, then the order and relevant sub-orders are set to status 'paid'.
  • Given a sub-order in status 'paid', when the seller starts preparing the shipment, then the seller can set the sub-order status to 'preparing'.
  • Given a sub-order in status 'preparing', when the seller ships the items, then the seller can set the sub-order status to 'shipped' and optionally provide tracking information.
  • Given a sub-order in status 'shipped', when the buyer or carrier confirms delivery, then the system can set the sub-order status to 'delivered'.
  • Given a payment failure or manual cancellation before shipment, when an order or sub-order is cancelled, then its status is set to 'cancelled' and it is clearly visible to buyer and seller.
  • Given a processed refund, when a refund is completed for an order or sub-order, then its status is set to 'refunded' and the buyer can see refunded amounts.
  • Given an order with multiple sub-orders, when I view the parent order, then I can see the overall status and the individual status of each sub-order.
  • Statuses: new, paid, preparing, shipped, delivered, cancelled, refunded.
  • State transitions should be constrained (e.g. cannot move from delivered back to preparing).
  • Notifications (email / in-app) should be triggered on key status changes, but detailed notification rules may be handled in a separate epic.
US-06-03 Buyer order list with filtering As a buyer I want to see a list of my orders with filters so that I can quickly find a specific order or check the status of recent purchases.
  • Given I am logged in as a buyer, when I open my orders section, then I see a paginated list of my parent orders sorted by creation date (newest first).
  • Given I have many orders in different statuses, when I filter by status (e.g. 'new', 'paid', 'shipped', 'delivered', 'cancelled', 'refunded'), then only orders matching the selected statuses are shown.
  • Given I have orders over a long period, when I filter by date range, then only orders created within that range are shown.
  • Given orders with multiple sellers, when I apply a seller filter, then only orders that contain sub-orders for that seller are shown or highlighted.
  • Given I see my order list, when I click an entry, then I am taken to the order detail view for that order.
  • Filtering options should at minimum include status and date range; seller filter is optional but recommended.
  • List must be limited to the authenticated buyer’s orders only.
  • Performance considerations: add indexes on buyer id, created date and status to support filtering at scale.
US-06-04 Seller order list with filtering and export As a seller I want to see a list of my sub-orders with filters and export so that I can manage fulfilment and reconcile orders with my internal systems.
  • Given I am logged in as a seller, when I open my orders section, then I see a paginated list of sub-orders that belong only to my store.
  • Given I have many sub-orders, when I filter by status, date range or buyer, then the list updates to show only matching sub-orders.
  • Given I need to process shipments in bulk, when I filter sub-orders by 'paid' or 'preparing', then I can focus on orders that require action.
  • Given I want to export my orders, when I choose export with a selected filter set, then the system generates an export file (e.g. CSV/XLS) containing at least order id, creation date, status, buyer, total amount and shipping method.
  • Given an export is generated, when the file is ready, then I can download it from the UI.
  • Export format should be compatible with common spreadsheet tools and potential ERP/WMS imports.
  • Access control: sellers must not see orders or buyer data for other sellers.
  • Large exports may require background processing and a download link rather than synchronous generation.
US-06-05 Buyer order detail view As a buyer I want to see detailed information about my order and seller sub-orders so that I can verify items, delivery details and current status.
  • Given I am a logged-in buyer with existing orders, when I open a specific order, then I see core information including order id, creation date, payment method, total amount and current overall status.
  • Given the order is split into multiple seller sub-orders, when I view the order details, then I see a section for each seller including items, quantities, prices, shipping cost and sub-order status.
  • Given the order has shipment tracking numbers provided by sellers, when I view the order details, then I see tracking numbers and, where available, links to carrier tracking pages.
  • Given the order has refunds or cancellations, when I view the order details, then I see which items or sub-orders were cancelled or refunded and the corresponding amounts.
  • Given I am not the owner of the order, when I try to access its details, then I am denied and see an appropriate error or redirect.
  • Order detail should hide any seller-sensitive internal notes not relevant to the buyer.
  • Design should make it clear that delivery dates and statuses may differ per seller for multi-seller orders.
  • Consider a separate section for returns/claims linked from the order detail.
US-06-06 Seller order detail view and buyer information As a seller I want to see full details of a sub-order so that I can prepare the shipment and handle communication with the buyer if needed.
  • Given I am logged in as a seller, when I open a sub-order from my list, then I see sub-order id, creation date, current status and the parent order id.
  • Given I am viewing a sub-order, when I check the line items section, then I see all items sold by my store in that sub-order with quantities, unit prices, taxes and totals.
  • Given I am viewing a sub-order, when I check the shipping section, then I see buyer’s delivery address, chosen shipping method and any delivery instructions that are relevant to fulfilment.
  • Given I am viewing a sub-order, when I check the buyer contact section, then I see minimal buyer contact data required for fulfilment (e.g. name, email, phone) as allowed by privacy rules.
  • Given I am logged in as a different seller, when I try to open a sub-order that does not belong to my store, then I am denied access.
  • Seller must not see payment card details or any sensitive financial data; payment status should be exposed in a safe, abstract way (e.g. 'paid', 'payment pending').
  • Buyer data shown must comply with GDPR/RODO rules defined for the platform.
  • Consider an activity log within the order detail (status changes, timestamps) to help with support and dispute resolution.
US-06-07 Seller updates fulfilment status As a seller I want to update the fulfilment status of my sub-orders so that buyers and the platform know the current progress of their shipment.
  • Given I am a seller viewing a sub-order in 'paid' status, when I begin preparing items, then I can change the sub-order status to 'preparing'.
  • Given I am a seller viewing a sub-order in 'preparing' status, when I ship the items, then I can change the status to 'shipped' and optionally enter a tracking number and carrier.
  • Given I am a seller viewing a sub-order in 'shipped' status, when I need to correct tracking information, then I can update the tracking number and carrier without changing the status history.
  • Given a sub-order that has not yet been shipped, when I need to cancel it (e.g. item unavailable), then I can request cancellation and the system changes its status to 'cancelled' and triggers the appropriate refund flow.
  • Given status changes performed by the seller, when the buyer opens order details or the order list, then the new statuses are visible in near real-time.
  • Only valid transitions should be allowed; business rules for cancellations and refunds may depend on payments and platform policies.
  • Status changes should be auditable with timestamps and user identity.
  • Consider rate limiting or constraints to prevent accidental multiple status changes (e.g. double-clicking).
US-06-08 Buyer initiates a basic return request As a buyer I want to initiate a basic return request for an order or sub-order so that I can start the return process when I am not satisfied with the received goods.
  • Given I am a logged-in buyer with at least one delivered sub-order, when I open the order detail, then I see an option to initiate a return for eligible items or sub-orders.
  • Given I choose to initiate a return, when I select items or sub-orders and provide a reason, then the system creates a return request and confirms submission to me.
  • Given a return request has been created, when the seller views their sub-orders, then they can see that a return has been requested for specific items or for the whole sub-order.
  • Given a return request is pending, when I open the order detail as a buyer, then I can see the return status (e.g. 'requested', 'approved', 'rejected', 'completed').
  • Given platform policies restrict return initiation to a certain time window after delivery, when I try to initiate a return outside that window, then the system blocks the action and shows an appropriate message.
  • Initial scope is 'basic' returns: no complex workflows, no automatic label generation required in Phase 1.
  • Refund execution rules may depend on the Payments/Finance module and will be coordinated with that epic.
  • Design should support extension to item-level returns and dispute management in later phases.
US-06-09 Partial fulfilment of sub-orders (Phase 2) As a seller I want to partially fulfil a sub-order so that I can ship available items while keeping the remaining items pending or cancelled.
  • Given I am a seller viewing a sub-order with multiple line items, when only some items are available to ship, then I can mark selected items as 'shipped' while leaving others in 'preparing' or 'new' status.
  • Given a sub-order is partially fulfilled, when the buyer views the order detail, then they can clearly see which items have been shipped and which are still pending or cancelled.
  • Given items within a sub-order are partially cancelled by the seller, when a refund is triggered, then refund amounts are calculated only for the cancelled items.
  • Given partial fulfilment logic is enabled, when financial reporting runs, then revenue and fees are calculated correctly per shipped and cancelled item.
  • This story is explicitly Phase 2 and must not block Phase 1 delivery of basic full-order fulfilment.
  • Requires item-level status tracking within a sub-order and may impact returns and refunds workflows.
  • Consider complexity for UX; ensure partial fulfilment is clearly communicated to buyers and sellers.
Send to GitHub

Implement marketplace payments and settlements with escrow model, automatic commissions, payouts, settlements and refunds.

ID Name Description Acceptance Criteria Notes Actions
US-01 Process online payments via provider As a buyer I want to pay for my order using card, bank transfer or BLIK so that I can complete checkout securely and conveniently.
  • Buyer can select card, bank transfer or BLIK and complete payment via provider.
  • Successful payment updates order status to 'paid'.
  • Failed payment updates order status to 'failed'.
  • BLIK code entry flow works and returns correct status.
  • Use secure redirect API.
  • Enable or disable payment methods per environment.
  • Ensure idempotency for provider retries.
US-02 Apply marketplace escrow payment model As a marketplace owner I want all buyer payments to flow through Mercato escrow so that we can control fund release and deduct commissions.
  • Payment is stored in escrow after successful confirmation.
  • Escrow amounts are split per seller.
  • Cancelled orders release escrow back to the buyer.
  • Multi-seller orders store separate escrow allocations.
  • Must support multi-seller transactions.
  • Escrow ledger must be auditable.
  • Eligibility for payout must be configurable.
US-03 Track and show payment statuses As a buyer I want to see payment status so that I understand whether payment succeeded.
  • Supported statuses: pending, paid, failed, refunded.
  • Webhook updates map provider status to internal status.
  • Failed status displays clear message to buyer.
  • Refunded orders show refunded amount.
  • Map external provider codes in one place.
  • Do not expose technical errors to buyers.
  • Sellers see only statuses relevant to their sub-orders.
US-04 Calculate commission per transaction As a finance manager I want automatic commission calculation so that platform revenue is accurately tracked.
  • Commission calculated at payment confirmation.
  • Different commission rules applied per category or seller.
  • Partial refunds recalculate commission.
  • Historical orders keep original commission values.
  • Support global and per-seller overrides.
  • Store values with high precision.
  • Commission calculation must be transactional.
US-05 Configure and execute seller payout schedule As a seller I want predictable payouts so that I can plan cash flow.
  • Eligible balances are aggregated by schedule.
  • Sellers see payout status: scheduled, processing, paid, failed.
  • Failed payouts store error reference.
  • Below-threshold balances roll over.
  • Support at least weekly payouts.
  • Retry logic required.
  • Payout batching recommended.
US-06 View payout history and details As a seller I want to view payout history so that I can reconcile finances.
  • Seller can view list of payouts with dates and amounts.
  • Seller can open payout details with order breakdown.
  • Filtering by date or status works.
  • Failed payouts show reason.
  • Export to CSV/XLS optional for later phase.
  • Financial data must be immutable.
  • Access control required.
US-07 Generate monthly settlements per seller As a finance manager I want monthly settlement reports so that accounting can close the month.
  • System generates settlement per seller at month end.
  • Admin can view totals and drill into orders.
  • Adjustments for previous months marked clearly.
  • Settlements can be exported or downloaded.
  • Calendar rules must be configurable.
  • Settlements align with payout history but remain independent.
  • Regeneration should keep audit history.
US-08 Issue automatic commission invoices As a finance manager I want automatic commission invoices so that sellers receive compliant financial documents.
  • System generates invoice per seller for monthly commissions.
  • Sellers can view invoice list with status.
  • Seller can download PDF invoice.
  • Corrections and credit notes displayed when applicable.
  • Invoices must follow legal rules.
  • Numbering must be unique and sequential.
  • Tax configuration must be flexible.
US-09 Handle full and partial refunds As a support agent I want to process refunds so that orders, balances and commissions remain accurate.
  • Full refunds return money to buyer and update balances.
  • Partial refunds adjust escrow, commission and seller balance.
  • Provider errors are logged and shown to agent.
  • Sellers can trigger refunds within business rules.
  • Follow legal return rules.
  • Partial refund math must prevent negative balances.
  • Refunds must be fully auditable.
Send to GitHub

Enable buyers to manage shipping addresses and allow sellers to configure shipping methods, costs and delivery times so that shipping options, tracking and logistics flows are handled consistently across the marketplace.

ID Name Description Acceptance Criteria Notes Actions
US-01 Manage buyer shipping addresses As a buyer I want to manage my shipping addresses so that I can quickly select the correct address during checkout.
  • Given I am a logged-in buyer, when I open the shipping addresses section in my account, then I can see a list of my saved shipping addresses or an empty state if none exist.
  • Given I am on the shipping addresses section, when I add a new address with all required fields, then the address is saved and appears in my list of addresses.
  • Given I have at least one saved address, when I edit an existing address and save changes, then the updated data is reflected in the list and used in future checkouts.
  • Given I have at least one saved address, when I delete an address that is not currently used in an active order, then the address is removed from my list.
  • Given I have multiple addresses, when I mark one as default, then that address is preselected during checkout.
  • Address fields must comply with supported countries and shipping providers.
  • Validation required for mandatory fields (name, street, postal code, city, country, phone).
  • For MVP, only one country or limited set of countries may be supported.
US-02 Use buyer address in checkout As a buyer I want my saved shipping addresses to be available during checkout so that I can quickly choose where my order should be delivered.
  • Given I am a logged-in buyer with saved addresses, when I go to checkout, then my default shipping address is preselected and other addresses are available to choose from.
  • Given I am a logged-in buyer without saved addresses, when I go to checkout, then I am asked to provide a shipping address and can choose to save it for future use.
  • Given I change the selected address during checkout, when I place the order, then the chosen address is stored on the order and visible in order details.
  • If shipping address is changed, available shipping options and costs may need to be recalculated.
  • Guest checkout behaviour should be aligned with identity & checkout decisions (guest may provide one-time address).
US-03 Configure seller shipping methods As a seller I want to configure shipping methods for my store so that buyers can choose how their orders are delivered.
  • Given I am a logged-in seller, when I open my shipping settings, then I can see a list of shipping methods configured for my store or an empty state if none exist.
  • Given I am on shipping settings, when I add a new shipping method with name, description and availability (e.g. country/region), then the method is saved and becomes available for eligible orders.
  • Given I have existing shipping methods, when I edit a method and save changes, then future orders use the updated configuration.
  • Given I have existing shipping methods, when I disable or delete a method, then it is no longer available at checkout but is still kept on existing orders for history.
  • Shipping methods may represent types like courier, parcel locker, postal service, in-store pickup.
  • For MVP, advanced rules (per product, per weight, per dimension) can be simplified to flat rules per store or per country.
  • UI should indicate clearly which methods are active vs inactive.
US-04 Configure shipping cost and delivery times As a seller I want to define shipping costs and estimated delivery times per shipping method so that buyers see predictable pricing and delivery expectations.
  • Given I am configuring a shipping method, when I set a base cost and estimated delivery time, then this information is saved and used during checkout and in order details.
  • Given my shipping method is limited to specific regions, when a buyer selects a shipping address outside those regions, then the method is not offered at checkout.
  • Given I update shipping cost or delivery time for a method, when a buyer starts a new checkout, then the new configuration is used while existing orders keep the previous values.
  • For MVP, costs may be flat per method; more complex pricing (weight-based, basket value thresholds) can be added later.
  • Delivery time should be displayed in a buyer-friendly format (e.g. 2–3 business days).
US-05 Display shipping options in checkout As a buyer I want to see available shipping options with price and delivery time during checkout so that I can choose the best option for my needs.
  • Given I have items from one or more sellers in my cart and a shipping address selected, when I open the shipping step in checkout, then I see available shipping methods per seller or per combined shipment, each with cost and estimated delivery time.
  • Given a shipping method is not available for the selected address, when I am on the shipping step, then that method is not displayed.
  • Given I select one shipping option per seller or per shipment, when I proceed to payment and place the order, then the selected methods and costs are stored on the order and visible in buyer and seller order details.
  • Given I try to proceed without selecting required shipping options, when I click continue, then I see a validation error instructing me to choose a method.
  • Order split into seller sub-orders must be reflected in how shipping options are presented and stored.
  • Totals calculation in checkout must include shipping costs per seller according to Shopping Cart & Checkout epic.
  • UX should avoid overloading buyer with technical details of multiple sub-orders.
US-06 Seller enters tracking numbers As a seller I want to add tracking numbers and carrier information to shipped orders so that buyers can track the delivery of their packages.
  • Given I am a seller with an order in a shippable status, when I open the order detail page, then I can enter tracking number and carrier name for each shipment or sub-order.
  • Given I save a valid tracking number, when I confirm, then the tracking data is stored and visible to the buyer in their order details.
  • Given tracking data exists for an order, when I update or correct the tracking number, then the new value replaces the old one and is logged for audit history if required.
  • Given tracking data exists, when the buyer views the order details, then a link or instructions are displayed to track the package on the carrier site if possible.
  • For MVP, tracking link may be a simple URL template per carrier; advanced integration is Phase 2.
  • Multiple shipments per order should be supported if partial fulfilment is enabled in the Orders & Fulfilment epic.
US-07 Update and show shipping status As a buyer I want to see the current shipping status of my order so that I know when to expect delivery.
  • Given an order has been placed and a shipping method selected, when the seller updates the fulfilment or shipping status (e.g. preparing, shipped, delivered), then the buyer can see the updated status in their order list and order details.
  • Given the shipping status changes to shipped, when this happens, then the buyer receives a notification (e.g. email) with shipping status and tracking information if available.
  • Given the shipping status changes to delivered (either manually or via integration in future), when the buyer views the order, then the status is clearly marked as delivered and the order is no longer shown as in transit.
  • Given the shipping status is updated, when the admin reviews the order in the back office, then the full history of shipping status changes is visible for support purposes.
  • Shipping statuses should align with overall order status model defined in Orders & Fulfilment epic.
  • For MVP, status updates are driven by seller actions; automatic updates from carriers will be added in Phase 2.
US-08 CSV export for logistics As a seller I want to export order and shipping data to CSV so that I can pass it to external logistics systems or partners.
  • Given I am a logged-in seller, when I open my order list view and choose an export option, then I can export selected orders to a CSV file containing key shipping fields (buyer name, address, phone, shipping method, order items, reference IDs).
  • Given I select a date range or filter (e.g. only new orders, only orders without tracking), when I run the export, then only matching orders are included in the CSV.
  • Given the CSV file is generated, when I download it, then it opens correctly in common tools (e.g. Excel) and has a clear header row.
  • Given there are no orders for the chosen filter, when I try to export, then the system informs me that there is nothing to export and no file is generated.
  • CSV structure should be documented for external logistics partners.
  • Export volume limits and pagination must be considered for performance.
  • Admin may need a similar export for platform-level logistics reporting in future.
US-09 Integrate shipping providers (Phase 2) As a platform owner I want to integrate Mercato with selected shipping providers so that sellers can automatically create shipments and keep buyers informed without manual data entry.
  • Given a shipping provider integration is configured for the platform, when a seller enables that provider in their shipping settings, then the provider becomes available as a shipping method or service for that seller.
  • Given an order is marked as ready to ship with an integrated provider, when the seller confirms shipment creation, then a shipment is created via provider API and tracking number is automatically stored on the order.
  • Given shipments are created via provider APIs, when provider sends status updates (e.g. in transit, delivered) or they are polled, then the order's shipping status is updated accordingly and visible to buyer and seller.
  • Phase 2 scope; not required for initial MVP.
  • Start with one or two key providers and make the integration design extensible.
  • Error handling for failed API calls and retries must be defined.
  • Security and credential management for provider APIs must follow platform standards.
US-10 Generate shipping labels (Phase 2) As a seller I want to generate shipping labels directly from Mercato so that I can speed up the packing and dispatch process.
  • Given an integrated shipping provider supports label creation, when a seller confirms shipment creation from the order screen, then a shipping label PDF is generated and stored for that shipment.
  • Given a label exists for a shipment, when the seller opens the order, then they can download or print the shipping label from the order details.
  • Given label generation fails, when the seller attempts to create a label, then the system shows a clear error message and does not mark the order as shipped.
  • Phase 2 scope; depends on shipping provider integration story.
  • Labels should be stored securely and cleaned up according to data retention policy.
  • Consider per-provider constraints on label formats, sizes and reprint rules.
Send to GitHub

Handle buyer return and complaint requests with a structured workflow, internal messaging, links to refund processing, and admin escalation.

ID Name Description Acceptance Criteria Notes Actions
US-01 Submit return or complaint request As a buyer I want to submit a return or complaint request for a specific order or item so that I can formally report a problem and ask for a resolution.
  • Given I am a logged-in buyer with at least one delivered or completed order, when I open the order details, then I can see an action to create a return or complaint request.
  • Given I start a return or complaint request, when I select item(s), specify reason, type (return or complaint) and provide a description, then I can submit the request.
  • Given I submit a valid request, when the system saves it, then I see a confirmation, a unique case ID, and the case appears in my list of cases with status 'Pending seller review'.
  • Given I submit an invalid or incomplete form (e.g. missing mandatory fields), when I click submit, then the system shows validation messages and does not create a case.
  • Requests must be linked to a concrete order and optionally to individual order lines.
  • Supported types at MVP: product issue (complaint) and standard return; more specific categories may be added later.
  • Buyer should not be able to open a new request for the same line item if an open case already exists.
US-02 View and track my cases as buyer As a buyer I want to see a list and details of my return and complaint cases so that I can track their status and outcomes.
  • Given I am a logged-in buyer, when I open the 'Returns & complaints' section, then I see a list of my cases with basic information (case ID, order reference, seller name, type, created date, current status).
  • Given I have at least one case, when I open its details, then I see the original request data, current status, resolution (if any), linked refund information (if any), and the messaging thread.
  • Given a case status changes (e.g. from 'Pending seller review' to 'In progress' or 'Resolved'), when I later open my case list, then I see the updated status.
  • Given a case is resolved, when I open it, then I can see whether it was approved, partially approved, or rejected, including the seller's final decision summary.
  • Filtering by status and date range is recommended but may be simplified in MVP.
  • Access must be restricted so that buyers cannot see cases belonging to other buyers.
  • Resolutions should surface any linked payment/refund identifiers from the payments module.
US-03 Seller review of incoming cases As a seller I want to review return and complaint requests related to my orders so that I can decide how to handle them.
  • Given I am a logged-in seller, when I open the 'Returns & complaints' section in my panel, then I see a list of cases for orders fulfilled by my store with key information (case ID, buyer alias, order reference, type, created date, status).
  • Given I open a specific case, when the system loads details, then I see buyer-submitted information (items, reasons, description, attachments if supported) and order/shipment context.
  • Given a case is in 'Pending seller review' status, when I choose an action (e.g. accept return, propose partial solution, request more information, reject), then the system updates the case status accordingly.
  • Given I take an action that changes the case status, when I save my decision, then the buyer is notified and the case history records my action and timestamp.
  • Seller should only see cases related to their own orders, not to other sellers' orders.
  • Available seller actions and resulting statuses should be defined globally to keep the workflow consistent across all sellers.
  • For multi-seller orders the platform may create separate cases per seller if needed.
US-04 Messaging thread inside a case As a buyer or seller I want to exchange messages inside a case so that we can clarify the issue without sharing private contact details.
  • Given a case exists, when a buyer or seller opens its details, then they see a chronological messaging thread with timestamps and sender roles.
  • Given I am the buyer or the seller associated with the case, when I type a message and submit it, then it is appended to the thread and visible to the other party.
  • Given a new message is added to a case, when the other party next views their notifications or case list, then they see that there is new activity on the case.
  • Given I am not related to the case, when I try to access its messaging thread, then access is denied.
  • Messaging should be text-only at MVP; attachments can be considered later.
  • System should prevent sharing of sensitive data (e.g. raw email addresses, phone numbers) if possible via UX guidelines.
  • Admins must be able to see the full thread for moderation and escalation.
US-05 Case resolution and refund linkage As a seller I want to record the final resolution of a return or complaint and trigger or link to refund processing so that the financial outcome is consistent with the case decision.
  • Given I am a seller viewing an open case, when I choose a resolution option (e.g. full refund, partial refund, replacement, repair, no refund) and confirm, then the case moves to a resolved status reflecting this decision.
  • Given I select a resolution that requires a refund, when I confirm the resolution, then the system either initiates a refund request to the payments module or prompts me to link an existing refund transaction.
  • Given the payments module confirms a successful refund, when I open the case details, then I see the refund reference, amount, and status linked to the case.
  • Given a case is resolved with 'no refund' or 'rejected', when the buyer views the case, then they see the decision reason provided by the seller.
  • Refund execution is owned by the payments/settlements module; this module must only initiate or link to that process.
  • Edge cases: partial refund for multi-item orders, multiple refunds per order, or refunds already processed outside the system must be handled gracefully.
  • Platform rules must define when a seller can still change the resolution (e.g. before or after refund is processed).
US-06 Admin view and escalation of cases As an admin I want to view and escalate return and complaint cases so that I can intervene when buyers and sellers cannot reach agreement or when platform rules are violated.
  • Given I am an admin, when I open the admin 'Returns & disputes' section, then I see a searchable and filterable list of all cases across the platform with key metadata (seller, buyer alias, status, age, type).
  • Given I open a case as an admin, when the system loads details, then I see the full case data including all messages, status history, and linked payment/refund information.
  • Given a case is in a conflict state (e.g. buyer disagrees with seller resolution or marked for escalation), when I choose to escalate it, then the case status changes to an 'Under admin review' status and the buyer and seller are notified.
  • Given I am reviewing an escalated case, when I record an admin decision (e.g. override seller decision, enforce refund, close without action), then the case is updated accordingly and the decision is added to the history.
  • Admins must have read-only access to sensitive data as required for dispute resolution.
  • Escalation entry points should be clearly defined (buyer-requested escalation, system SLA breach, manual admin flag).
  • Audit logs for admin actions are required for compliance and internal review.
US-07 SLA tracking for case handling (Phase 2) As an admin I want to track SLAs for return and complaint cases so that I can monitor seller responsiveness and enforce platform standards.
  • Given SLA tracking is enabled, when a new case is created, then the system records creation time and calculates SLA deadlines for first response and resolution based on configuration.
  • Given a case is pending seller action, when the SLA deadline for first response or resolution is exceeded, then the system flags the case as 'SLA breached' and surfaces it in admin views.
  • Given SLA metrics are recorded, when I open the SLA dashboard as an admin, then I can see aggregate SLA statistics (e.g. percentage of cases resolved within SLA, average response time) per seller over a selected period.
  • This story is Phase 2 and should be designed so it can be added without breaking core MVP flows.
  • SLA configuration (thresholds, per-category rules) should be stored centrally and editable by admins only.
  • SLA breaches may automatically trigger soft escalation flows (e.g. notifications, case highlighting) even before full admin dispute handling.
Send to GitHub

Support product and seller review flow, rating visibility, moderation and reporting to build trust across the marketplace.

ID Name Description Acceptance Criteria Notes Actions
US-010-01 Submit product review As a buyer I want to submit a rating and review after my order is delivered so that I can share my experience with other buyers.
  • Given a delivered order, when the buyer opens the review form, then the system allows entering rating and text feedback.
  • Given the review is submitted, when validation passes, then the review becomes visible publicly after moderation if needed.
  • Review available only after order status = delivered.
  • Optional photo attachments may be added later.
  • Ensure rate limiting to avoid spam submissions.
US-010-02 Display product reviews As a buyer I want to see product reviews so that I can make an informed purchase decision.
  • Given a product page, when it loads, then the system displays average rating and the list of approved reviews.
  • Given the product has no reviews, when viewed, then the system displays a placeholder message.
  • Sort options: newest, highest rating, lowest rating.
  • Pagination required for large review counts.
US-010-03 Rate seller after order As a buyer I want to rate a seller based on completed orders so that the platform can track seller performance.
  • Given an order is delivered, when the buyer opens the seller rating form, then the user can select a rating value.
  • Given the rating is submitted, when stored successfully, then it affects the seller's rating score.
  • Only one rating per order.
  • Seller rating contributes to overall reputation score.
US-010-04 Display seller rating As a buyer I want to see a seller’s rating on their store page so that I can evaluate their reliability.
  • Given a seller page is opened, when data is loaded, then the system shows average seller rating and number of completed rated orders.
  • Seller rating aggregated as rolling average.
  • Future weighting based on recent performance.
US-010-05 Moderate reviews As an admin I want to moderate reviews so that inappropriate or fraudulent content is removed.
  • Given a new review is submitted, when flagged by automated rules or manually reported, then admin can approve, reject or edit visibility.
  • Given a review is rejected, when removed, then it no longer appears publicly.
  • Moderation may include keyword search, automated filters and manual actions.
  • Audit log is required.
US-010-06 Report a review As a buyer I want to report a review so that inappropriate content can be reviewed by admins.
  • Given a review is visible, when buyer clicks 'Report', then system stores a report entry for admin review.
  • Report reasons: abuse, spam, false information, other.
  • Must prevent duplicate reports by the same user.
US-010-07 Seller reputation score (Phase 2) As a system I want to calculate an aggregated reputation score so that the marketplace can highlight trusted sellers.
  • Given a seller has activity history, when the system runs reputation calculation, then it updates the seller’s reputation score based on defined formula.
  • Given the updated score, when displayed, then buyers see simplified reputation metrics.
  • Reputation formula may include: seller ratings, dispute rate, on-time shipping rate, cancelled orders.
  • Requires periodic recalculation (batch or event-driven).
  • Phase 2 scope.
Send to GitHub

Unified notifications and communication layer for Mercato, covering email notifications, in-app notification center, internal messaging, and web push.

ID Name Description Acceptance Criteria Notes Actions
US-01 Email notifications for buyers As a buyer I want to receive email notifications for registration and order events so that I stay informed about my account and purchases.
  • Buyer receives an email after successful registration.
  • Buyer receives an order confirmation email after placing an order.
  • Buyer receives a shipping email when seller marks an order as shipped.
  • Buyer receives a payout or refund confirmation email.
  • Emails use correct templates, localization and sender address.
  • Covers registration, order confirmation, shipping updates and payout/refund emails.
  • Requires integration with transactional email provider.
  • Logs email send attempts and results.
US-02 Email alerts for sellers As a seller I want to receive email alerts about new orders, returns and payouts so that I can react quickly and track my cash flow.
  • Seller receives email when a new order is placed for their products.
  • Seller receives email when a return or complaint is created.
  • Seller receives email when a payout is processed.
  • Email links redirect to relevant order, return or payout view after login.
  • Covers seller-facing events.
  • Supports multiple seller users in the future.
  • Emails sent only after business event is committed in the system.
US-03 Notification center As a logged-in user I want to see a notification center so that I can manage all my notifications in one place.
  • User sees notification icon with unread counter.
  • Opening notification center displays a list of recent notifications.
  • Clicking a notification opens the related page.
  • User can mark notifications as read.
  • Empty state is shown when there are no notifications.
  • Covers order events, returns, payouts, messages, system updates.
  • Supports filtering by read/unread and pagination.
  • Later phases may add advanced preferences.
US-04 Internal messaging (Phase 1.5) As a buyer I want to ask questions about a product or order so that I can clarify details without leaving the platform.
  • Buyer can submit product questions from product page.
  • Seller receives notification about new question.
  • Seller can answer and buyer is notified.
  • Order-related messaging is private between buyer and seller.
  • Only buyer, seller and admin can access message thread.
  • Phase 1.5 scope.
  • Supports product Q&A and private order messages.
  • Requires basic moderation tools for admins.
US-05 Web push notifications (Phase 2) As a frequent user I want to receive web push notifications so that I see important events even when Mercato is not open.
  • User is asked for permission to receive push notifications.
  • After permission, user receives push notifications for key events.
  • Clicking push notification opens the relevant view.
  • User can disable push notifications in settings or browser.
  • Phase 2 feature depending on service worker.
  • Limited set of high-value events initially.
  • Requires push infrastructure and per-user device registration.
Send to GitHub

Provide reporting and analytics dashboards for admins and sellers to monitor marketplace performance and support data-driven decisions.

ID Name Description Acceptance Criteria Notes Actions
EP12-US-01 Admin marketplace performance dashboard As an admin I want to see a dashboard with GMV, orders, active sellers, products and new users so that I can quickly assess the overall health of the marketplace.
  • Given I am logged in as an admin, when I open the reporting dashboard, then I see KPIs for total GMV, number of orders, number of active sellers, number of active products and number of newly registered users for the selected period.
  • Given I am on the admin dashboard, when I change the date range (e.g. today, last 7 days, last 30 days, custom range), then all KPIs and charts refresh to reflect the selected period.
  • Given I am on the admin dashboard, when there is no data for the selected period, then the dashboard shows zero values and an informational message instead of an error.
  • Given I am on the admin dashboard, when I click on a KPI tile (e.g. orders), then I am taken to a detailed report filtered for that metric and period.
  • Given the system receives new orders and registrations, when I refresh the admin dashboard, then metrics are updated according to the latest data with a visible information about last refresh time.
  • GMV definition must be agreed (e.g. gross order value including shipping and before commission).
  • Active sellers should be defined (e.g. at least one product online OR at least one order in selected period).
  • Active products should be defined (e.g. products in 'active' status).
  • Date range presets should be aligned with global reporting patterns used in other modules.
EP12-US-02 Seller sales dashboard As a seller I want to see a sales dashboard over time so that I can understand my performance and trends.
  • Given I am logged in as a seller, when I open my analytics dashboard, then I see a chart of my sales over time (e.g. daily or weekly GMV and number of orders) for the selected period.
  • Given I am on the seller dashboard, when I change the time granularity (e.g. day, week, month) where available, then the chart and totals are recalculated accordingly.
  • Given I am on the seller dashboard, when I filter by product or category, then the chart and KPIs show data only for the selected products or categories.
  • Given I am a seller, when I view my dashboard, then I only see my own sales data and never data of other sellers.
  • Given there is no sales data for the selected period, when I open the seller dashboard, then the system shows an empty-state message with guidance instead of an error.
  • Sales metrics should reuse the same GMV definition as the admin dashboard.
  • Initial version may support a limited set of filters (e.g. date range and basic product filter).
  • Chart type (line, bar) should be chosen for clarity on mobile and desktop.
  • Performance of queries must be acceptable for high-order-volume sellers.
EP12-US-03 Admin order and revenue reports with CSV export As an admin I want to generate order and revenue reports with CSV export so that I can analyse marketplace performance outside the system.
  • Given I am logged in as an admin, when I open the order and revenue report page, then I can filter data by date range, seller, order status and payment status.
  • Given I have applied filters on the report page, when I click 'Apply' or similar, then the table shows matching orders with key fields (order id, date, buyer, seller, status, payment status, order value, commission, payout amount).
  • Given a filtered report is displayed, when I click 'Export CSV', then a CSV file is generated containing all rows that match the current filters.
  • Given the CSV export is generated, when I open it in Excel or similar tools, then the file structure is valid and column headers match the report fields.
  • Given I request a very large report (above a configured threshold), when the system generates the CSV, then it either paginates or informs me about background generation according to agreed UX rules instead of timing out.
  • Large exports may need limits or asynchronous processing depending on data volume.
  • CSV delimiter and encoding should follow platform conventions (e.g. UTF-8 and comma or semicolon based on locale).
  • Report should be extendable with new columns in future without breaking existing consumers.
  • Access to reports must be restricted to admin users only.
EP12-US-04 Seller order and revenue reports with CSV export As a seller I want to generate order and revenue reports with CSV export so that I can reconcile my sales and import data into my own systems.
  • Given I am logged in as a seller, when I open my order and revenue report, then I see only orders that belong to my store.
  • Given I am on the seller report page, when I filter by date range and order status, then the table refreshes and shows matching orders with basic financial fields (order value, commission charged, net amount to seller).
  • Given I have filtered my report, when I click 'Export CSV', then I receive a CSV file containing only my orders that match the current filters.
  • Given I open the CSV export in a spreadsheet tool, when I check the sums, then total amounts match what I see in the on-screen report for the same filter.
  • Given there are no orders for the selected period, when I attempt a CSV export, then the system generates an empty file with headers or informs me that no data is available.
  • Seller exports must never contain data of other sellers.
  • Format should be compatible with typical accounting and ERP tools of sellers.
  • Commission and net amounts should be calculated consistently with the payments and settlements module.
  • Initial version may limit filters to date and status; more filters can be added later.
EP12-US-05 Admin commission summaries As an admin I want to see commission summaries per seller and period so that I can validate platform revenue and settlements.
  • Given I am logged in as an admin, when I open the commission summary view, then I can select a date range and see a table grouped by seller with total GMV, total commission amount and total net payout for that period.
  • Given I am on the commission summary view, when I click into a seller row, then I can see a drill-down list of the individual orders contributing to the totals.
  • Given I am on the commission summary view, when I export the summary to CSV, then the CSV includes one row per seller with all aggregated values for the selected period.
  • Given settlements are generated by the payments module, when I view commission summaries, then totals are consistent with the amounts shown in monthly settlements.
  • Given there is a configuration change in commission rates, when I generate a summary for a historical period, then the report uses historical commission rates stored with each order.
  • Aggregation logic must be aligned with the payments & settlements module.
  • Commission rates may differ per seller or category; calculation should use persisted per-order data rather than recalculating.
  • Consider performance impact for large numbers of sellers and orders.
  • Access to commission data must be restricted to admins and potentially finance roles only.
EP12-US-06 Basic registration and activity analytics As an admin I want to see basic registration and activity analytics so that I can understand user growth and engagement.
  • Given I am logged in as an admin, when I open the user analytics section, then I see metrics such as number of new buyer accounts, number of new seller accounts and total active users for the selected period.
  • Given I am on the user analytics section, when I change the date range, then the metrics and charts update accordingly.
  • Given I am on the user analytics section, when I view activity metrics, then I can see at least the number of users that placed an order and number of users that logged in within the selected period.
  • Given I am on the user analytics section, when there is insufficient data for a metric, then the system shows an explanatory message rather than misleading or empty numbers.
  • Given privacy constraints apply, when I navigate through user analytics, then I only see aggregated, anonymised information and not individual user-level personal data.
  • Definitions of 'active user' and 'active seller' must be agreed with business (e.g. at least one login or order in period).
  • Metrics should be based on existing event and audit data where possible.
  • Analytics must comply with privacy and GDPR requirements (aggregated metrics, no unnecessary personal data).
  • This story covers basic counts and simple charts, not full behavioural analytics.
EP12-US-07 Instrumentation for advanced analytics (Phase 2) As a product owner I want key events and data points to be tracked so that we can build advanced analytics dashboards in Phase 2.
  • Given the system is processing user actions, when a user performs key events (e.g. search, product view, add to cart, checkout start, order completion), then these events are recorded in a way that can be queried later for analytics.
  • Given we have defined a minimal tracking schema, when developers implement event logging, then each event contains at least timestamp, user or session identifier, event type and relevant business identifiers (e.g. product id, seller id, order id).
  • Given tracking is enabled, when I or a data analyst query the analytics storage with basic tools, then I can retrieve events for a given time range and filter by event type.
  • Given Phase 1 should not expose advanced analytics UI, when I log in as admin or seller, then I do not see incomplete or placeholder advanced analytics screens.
  • Given tracking can affect performance and storage, when we enable event logging, then it is configurable and monitored to avoid critical impact on core flows.
  • This story focuses on data collection and storage required for Phase 2 advanced analytics, not on UX/UI of those analytics.
  • Choice of analytics storage (e.g. separate database, data warehouse, external analytics tool) must be aligned with overall architecture decisions.
  • Event tracking must comply with privacy and cookie/consent policies.
  • Advanced dashboards, funnels and cohorts will be designed and implemented in Phase 2 using this data.
Send to GitHub

Provide administrators with tools to manage users, content, platform settings, categories, integrations and feature flags to keep the Mercato marketplace safe, compliant and configurable.

ID Name Description Acceptance Criteria Notes Actions
US-13-01 Admin views and filters user accounts As an admin I want to view and filter user accounts so that I can quickly find and review specific buyers or sellers.
  • Given there are buyer, seller and admin accounts in the system, when I open the admin user management screen, then I see a list of users with key attributes such as ID, role, email, status and creation date.
  • Given I am on the user list, when I filter by role or account status, then only users matching the selected criteria are displayed.
  • Given I am on the user list, when I search by email, name or user ID, then matching users are shown in the results.
  • Given I am viewing a specific user record, when I open the user detail view, then I see extended information such as role, recent login activity, verification status and any flags or notes.
  • Account statuses should at least include: Active, Blocked, Pending verification.
  • Ensure pagination or infinite scroll for large user bases.
  • Respect data protection rules – only show personal data that is necessary for admin operations.
US-13-02 Admin blocks a user account As an admin I want to block user accounts so that I can prevent abusive or fraudulent users from accessing the platform.
  • Given a user account is currently active, when I click the action to block the account and confirm, then the user status changes to Blocked and the action is recorded in an audit log.
  • Given a user account is blocked, when the user attempts to log in, then the login is rejected with a clear message explaining that the account is blocked.
  • Given I blocked a user account, when I open the user detail view, then I see who blocked it, when it was blocked and an optional reason.
  • Given platform-wide rules exist, when I block a seller account, then their public store page and listings are no longer visible to buyers.
  • Blocking should not permanently delete data for legal and audit reasons.
  • Consider separate reasons for blocking (fraud, spam, policy violation) for reporting.
  • Admin audit log should capture actor, timestamp and reason.
US-13-03 Admin reactivates a user account As an admin I want to reactivate blocked user accounts so that I can restore access when issues are resolved.
  • Given a user account is blocked, when I select the option to reactivate and confirm, then the user status changes back to Active and this change is recorded in the audit log.
  • Given a user account was reactivated, when the user next attempts to log in, then they can log in normally subject to standard security checks.
  • Given I am viewing user details, when I open the account history, then I see the full block/reactivate history with timestamps, admin names and reasons.
  • Reactivation should not reset passwords or other security data by default.
  • Consider optional requirement for user to reset password after reactivation for high-risk cases.
US-13-04 Admin moderates products As an admin I want to review and moderate products so that prohibited or low-quality listings do not appear on the marketplace.
  • Given sellers have created products, when a product is flagged for review or enters a moderation queue, then I can open its details including title, description, images, category and seller information.
  • Given I am reviewing a product, when I approve it, then its status becomes Active and it is visible in search and listings for buyers.
  • Given I am reviewing a product, when I reject it and provide a reason, then its status becomes Rejected, it is not visible to buyers and the seller receives a notification with the reason.
  • Given there are many products awaiting moderation, when I open the product moderation screen, then I can filter by status (Pending, Approved, Rejected) and category and perform bulk approve/reject operations.
  • Link moderation decisions with seller notifications via email and/or in-app messages.
  • Maintain a history of moderation decisions per product for audit and dispute resolution.
  • Integrate with existing product workflow statuses (e.g. draft, active, suspended, archived).
US-13-05 Admin moderates product photos As an admin I want to moderate product photos so that illegal or inappropriate images are not shown to buyers.
  • Given sellers upload product photos, when a photo is flagged by automatic checks or by users, then it appears in a photo moderation queue with a link to the related product and seller.
  • Given I am reviewing a photo, when I mark it as approved, then the photo remains visible on the product page and the decision is stored.
  • Given I am reviewing a photo, when I mark it as removed and provide a reason, then the photo is no longer displayed on the product page and the seller is notified.
  • Given a product has multiple photos, when I remove one photo, then the remaining photos still display correctly without breaking the gallery.
  • Consider integration with automated image screening services in later phases.
  • Ensure removed photos are archived or anonymised rather than hard-deleted if legal retention is required.
US-13-06 Admin moderates reviews As an admin I want to review and moderate product and seller reviews so that abusive or misleading content is removed from the platform.
  • Given buyers leave reviews for products or sellers, when a review is reported or flagged by automated rules, then it appears in a review moderation queue with review text, rating, reviewer and target entity.
  • Given I am reviewing a review, when I decide it is acceptable and approve it, then it remains visible or changes its status to Published.
  • Given I am reviewing a review, when I decide it violates rules and remove it, then it is no longer visible to buyers and a record of the decision including reason is stored.
  • Given I remove a review, when I check the target product or seller page, then overall rating metrics are updated to exclude the removed review.
  • Support reasons and categories for removal (hate speech, spam, off-topic, personal data, etc.).
  • Consider limited visibility to the author (e.g. informing them that their review was removed with a short explanation).
US-13-07 Admin manages commission rates and fees As an admin I want to configure commission rates and platform fees so that the marketplace revenue model can be managed without code changes.
  • Given I have access to platform settings, when I open the commissions and fees configuration screen, then I see current default commission rate, fixed fees and any category-specific overrides.
  • Given I create or edit a commission rule, when I set parameters such as rate, applicability (e.g. by category, seller type) and effective date, then the rule is saved and a confirmation is shown.
  • Given future-dated commission changes exist, when a transaction occurs on or after the effective date, then the correct rule is applied to the transaction.
  • Given multiple commission rules could overlap, when I save a new rule, then the system validates for conflicts and informs me of any overlapping configurations that require resolution.
  • Support different commission rates by product category or seller segment in later phases.
  • All changes should be versioned and auditable for financial and legal purposes.
  • Commission logic must integrate with the payments and settlements module.
US-13-08 Admin manages VAT and tax settings As an admin I want to manage VAT and tax settings so that calculations and invoices are compliant with local regulations.
  • Given I have access to platform settings, when I open the VAT configuration screen, then I can see defined VAT rates per country and category where applicable.
  • Given I create or update a VAT rule, when I specify country, tax rate, applicable categories and effective dates, then the rule is stored and used in subsequent price and invoice calculations.
  • Given VAT rules change over time, when I define a new rate with a future effective date, then existing transactions continue to use the current rate until the new date.
  • Given I change a VAT rule, when an admin or finance user views the VAT history, then previous and current rates with timestamps and author information are visible.
  • Integrate with the invoicing component to ensure correct tax breakdown on documents.
  • Consult legal and tax advisors for country-specific rules; model should support multiple jurisdictions.
US-13-09 Admin manages currencies and platform currency settings As an admin I want to configure available currencies and base currency so that the platform can operate in multiple markets.
  • Given I have access to platform settings, when I open the currency configuration section, then I can see the base currency and list of enabled currencies for display and transactions.
  • Given I enable or disable a currency, when I save the change, then the currency becomes available or unavailable for new listings and transactions accordingly.
  • Given external exchange rates are provided by another module or integration, when I view a currency, then I can see its last update time and rate source.
  • Given changing base currency has major impact, when I attempt to change the base currency, then the system warns me and may require an additional confirmation or admin role.
  • Exchange rate loading is handled in another module; here only configuration of available currencies and base currency is managed.
  • Ensure that disabling a currency does not break existing historical data or reports.
US-13-10 Admin manages categories As an admin I want to manage the product category tree so that the marketplace taxonomy can evolve with business needs.
  • Given I am in the category management screen, when I create a new category with a name, parent category and optional description, then it appears in the category tree.
  • Given categories exist, when I drag and drop or edit a category to change its parent, then the hierarchy updates and is reflected in search and navigation.
  • Given a category is in use by products, when I attempt to delete it, then I am either blocked or required to reassign affected products to another category.
  • Given I update a category name or slug, when I save changes, then breadcrumb navigation and category URLs update consistently without breaking existing links beyond defined rules.
  • Support multi-level hierarchies (e.g. up to N levels).
  • Consider SEO implications when renaming or moving categories (redirects, canonical URLs).
  • Category management will be used by product catalog and search modules.
US-13-11 Admin manages attribute templates for categories As an admin I want to define attribute templates per category so that product data is structured and search filters work correctly.
  • Given I open the attributes management section for a category, when I add a new attribute with name, type (e.g. text, number, list) and required flag, then it becomes part of that category’s attribute template.
  • Given attributes exist for a category, when a seller creates or edits a product in that category, then the defined attributes are presented as structured fields.
  • Given an attribute is no longer needed, when I mark it as deprecated, then it is hidden from future product creation but remains visible for existing products and reports.
  • Given attributes are shared across multiple related categories, when I update a shared attribute definition, then changes are reflected for all linked categories.
  • Attribute types and validation rules should be reusable across categories.
  • Changes to attributes must not cause data loss in existing products.
  • This story provides the admin part; seller-side behaviour is covered in Product Catalog epics.
US-13-12 Admin manages integrations As an admin I want to configure and monitor external integrations so that connections to payment providers, logistics and other systems can be managed centrally.
  • Given I open the integrations management screen, when I view the list, then I see each configured integration with its name, type (e.g. payment, shipping, ERP), status and environment (sandbox/production).
  • Given an integration supports configuration, when I open its detail view, then I can edit settings such as API keys, endpoints, merchant IDs and callback URLs and test the connection.
  • Given an integration is misconfigured or unreachable, when I run a health check, then I receive a clear status and error message to help diagnose the issue.
  • Given I temporarily disable an integration, when the marketplace tries to use it, then calls are blocked gracefully and fallbacks or error messages are shown to users as designed.
  • Store secrets securely and never show full values once saved (mask API keys).
  • Provide per-environment configuration (dev, test, prod) where applicable.
  • Integrations include but are not limited to payment gateway, shipping providers and future ERP/e-commerce connectors.
US-13-13 Admin manages legal content As an admin I want to manage legal documents such as Terms of Service and Privacy Policy so that the platform remains compliant and up to date.
  • Given I open the legal content management screen, when I select a document type (e.g. Terms of Service, Privacy Policy, Cookie Policy, Seller Agreement), then I can view and edit its current version.
  • Given I create a new version of a legal document, when I set its effective date and save, then the system stores it as a new version while keeping old versions for reference.
  • Given a new legal version has a future effective date, when a user visits the document before that date, then they see the current active version and optionally a notice about upcoming changes.
  • Given a new version becomes effective, when new users accept terms during registration or checkout, then their consent is associated with that version identifier.
  • Legal content should support rich text/HTML and localisation in multiple languages in later phases.
  • Consent tracking must integrate with registration and checkout flows to support audit and compliance.
  • Provide view-only access for legal/Compliance roles if needed.
US-13-14 Admin views audit logs As an admin I want to view audit logs of administrative actions so that I can investigate issues and ensure accountability.
  • Given admin actions such as user status changes, moderation decisions and settings updates are logged, when I open the audit log screen, then I can see entries with timestamp, admin user, action type, target entity and optional details.
  • Given many log entries exist, when I filter by date range, admin user, entity type or action type, then only matching entries are shown.
  • Given I need to investigate a specific resource, when I open the log filtered by resource ID, then I see its full change history.
  • Given security requirements, when a non-authorised admin attempts to open the audit logs, then access is denied.
  • Audit logs should be immutable and stored in a tamper-resistant way where feasible.
  • Define retention policy for audit data in line with legal and operational needs.
US-13-15 Admin manages feature flags (Phase 2) As an admin I want to manage feature flags so that I can enable, disable or roll out new features gradually without redeploying code.
  • Given feature flags are supported by the platform, when I open the feature flag management screen, then I can see a list of flags with name, description, status and optional targeting rules.
  • Given I create a new feature flag, when I define its key, description, default state and environments, then the flag is saved and available to the application at runtime.
  • Given a feature flag is configured with target segments (e.g. internal users, specific sellers, percentage rollout), when the system evaluates the flag for a request, then it returns the correct on/off value according to rules.
  • Given I toggle a feature flag from off to on for production, when users refresh the application, then the associated feature becomes available or hidden accordingly without a new deployment.
  • Phase 2 scope – underlying runtime evaluation mechanism must be designed with engineering team.
  • Support separation by environment (dev/test/stage/prod) and possibly by tenant or user group.
  • All flag changes should be logged in audit logs for traceability.
Send to GitHub

Ensure Mercato processes and stores data securely and in line with GDPR, with proper access control, user rights handling, encryption and auditability across the platform.

ID Name Description Acceptance Criteria Notes Actions
US-01 Manage GDPR processing registry As a Compliance Officer I want to maintain a registry of personal data processing activities so that Mercato can demonstrate GDPR compliance at any time.
  • Given I am logged in as an admin or compliance role, when I open the data processing registry module, then I can see a list of all existing processing activities with key attributes (purpose, legal basis, categories of data, data subjects, processors, retention).
  • Given I provide all required fields, when I create a new processing activity record, then the record is saved, validated for completeness and visible in the registry list.
  • Given there is an existing processing activity record, when I edit its details and save, then changes are versioned or timestamped so that I can see who changed what and when.
  • Given I have appropriate permissions, when I export the processing registry, then I receive a structured file (e.g. CSV/XLSX) containing all processing activities and their attributes.
  • Data model must align with GDPR Art. 30 requirements.
  • Access limited to admin/compliance roles only.
  • Consider future integration with external legal/compliance tools.
US-02 Configure role-based access control As a System Owner I want a role-based access control model so that access to Mercato modules and actions is restricted according to user responsibilities.
  • Given the list of platform roles (e.g. buyer, seller, admin, support, compliance), when I review the RBAC configuration, then I can see which permissions and modules are assigned to each role.
  • Given I am an authorized admin, when I assign or revoke permissions for a role, then the changes take effect for all users with that role after the next authorization check.
  • Given a user without permission to access a module or action, when they try to reach it via UI or API, then the system denies access with an appropriate error and does not expose protected data.
  • Given an existing user, when I change their role, then their effective permissions are recalculated and applied to all new requests.
  • RBAC must be enforced consistently on backend APIs and UI.
  • Avoid hardcoding permissions in UI; use a central permission model.
  • Prepare for future custom roles or per-tenant overrides.
US-03 Enforce access control across modules As a Security Officer I want role-based access control to be enforced consistently across all Mercato modules so that users cannot access data or actions outside their authorization.
  • Given the RBAC configuration, when a seller tries to access another seller's orders or products, then the system blocks access and returns an authorization error.
  • Given a buyer is authenticated, when they access their own orders and account data, then the system allows access but does not expose other users’ data.
  • Given an admin or support user accesses sensitive views (e.g. full customer profile, payout details), when the access is granted, then this action is recorded in the audit log with user id, time and resource identifier.
  • Use a common authorization middleware or policy layer.
  • Include multi-tenant isolation (shop-level segregation) in checks.
  • Link to audit logging stories for sensitive access events.
US-04 Manage and store user consents As a Compliance Officer I want to manage user consents for data processing and communication so that Mercato only processes data within the scope of granted permissions.
  • Given a new buyer registers, when consents are presented, then each consent is clearly described, optionally pre-selected only where legally allowed, and requires explicit user action to accept.
  • Given a user views their privacy settings, when they open the consent section, then they can see all active consents with date and version of the consent text.
  • Given a user changes their consent (grants or withdraws), when they save changes, then the system updates the consent record with timestamp and retains previous versions for audit purposes.
  • Given email/marketing communications are sent, when the system checks eligibility, then messages are only sent to users with valid, active consent for that communication type.
  • Consent texts must be versioned and linked to each decision.
  • Support different consent types (e.g. newsletter, profiling, third-party sharing).
  • Ensure UI is localized and understandable for end users.
US-05 Provide user data export (Right of Access) As a Buyer or Seller I want to export my personal data so that I can exercise my GDPR right of access and review what Mercato stores about me.
  • Given I am logged in, when I navigate to the privacy or account section, then I can request an export of my personal data.
  • Given I request a data export, when the export is prepared, then I receive a downloadable file or secure link with my personal data structured in a readable and commonly used format (e.g. JSON or CSV within a ZIP).
  • Given system data spans multiple modules (identity, orders, messages), when the export is generated, then it includes all relevant personal data linked to my identity within defined scope.
  • Given an export is generated, when an admin or support user reviews logs, then they can see that a data export was requested and completed for the specific user with timestamp.
  • Clarify SLA for export generation (immediate vs. asynchronous).
  • Exclude internal security logs unless legally required.
  • Ensure export does not include other users’ personal data.
US-06 Handle user account deletion with anonymization As a Buyer or Seller I want to delete my account with proper anonymization so that my personal data is removed while necessary transactional history is preserved for legal reasons.
  • Given I am logged in and have no blocking conditions (e.g. open disputes), when I request account deletion, then the system informs me about the impact (loss of access, data anonymization).
  • Given my account deletion is confirmed, when the process completes, then my login credentials and personal identifiers are removed or irreversibly pseudonymized, and I can no longer sign in.
  • Given past orders and financial records must be retained, when anonymization runs, then personal attributes (name, email, phone, address) in those records are replaced with anonymized values while business-critical fields (amounts, dates, product ids) are kept.
  • Given an account deletion occurred, when an admin checks the audit log, then they can see who triggered the deletion, for which account, and when, without exposing the deleted personal data.
  • Align retention rules with legal and tax requirements in target markets.
  • Design anonymization routines per entity to avoid partial leaks.
  • Restrict account deletion for users with unresolved disputes or chargebacks.
US-07 Encrypt data at rest and in transit As a Security Officer I want personal and sensitive data to be encrypted at rest and in transit so that the impact of potential breaches is minimized.
  • Given the production environment is configured, when data is stored in databases and file storage (e.g. backups, logs with personal data), then storage-level or field-level encryption is enabled according to security standards.
  • Given clients use the web application or APIs, when they connect to Mercato, then all traffic is served over HTTPS/TLS and insecure protocols are redirected or blocked.
  • Given encryption keys are used, when the system is deployed, then keys are stored and rotated using a managed key management service and are not hardcoded in source code or configuration files.
  • Given an internal or external security audit is performed, when encryption settings are reviewed, then the platform passes checks for minimum cipher standards and key management practices.
  • Prefer cloud provider-managed encryption and KMS where available.
  • Define which fields require application-level encryption (e.g. partial card tokens, national IDs).
  • Document key rotation and incident procedures in runbooks.
US-08 Audit logging of critical actions As a Security Officer I want critical actions in the system to be audit logged so that suspicious activities can be detected and investigated.
  • Given a user performs a critical action (e.g. login, role change, payout change, order status override, refund, account deletion), when the action completes, then an audit log entry is created with user id, action type, target resource, timestamp, and outcome (success/failure).
  • Given audit logs exist, when an admin or security role accesses the audit log viewer, then they can filter entries by user, action type, time range and result.
  • Given audit logs are sensitive, when non-privileged users access the system, then they cannot view or modify audit log data.
  • Given retention policies are configured, when audit logs exceed the retention period, then they are archived or deleted according to policy while ensuring integrity up to the retention date.
  • Use append-only storage or tamper-evident mechanisms for critical logs.
  • Consider offloading logs to a centralized logging platform (e.g. SIEM).
  • Define which actions are considered critical with product and legal teams.
US-09 Log and manage security incidents As a Security Officer I want security incidents to be logged and tracked so that Mercato can respond and document them in a structured way.
  • Given a potential security incident is detected (e.g. multiple failed logins, suspicious API usage, data access anomaly), when the detection rule triggers, then an incident record is created with initial details (time, source, rule, severity).
  • Given an incident record exists, when a security user updates its status (e.g. triaged, in investigation, resolved), then the status change is persisted with timestamp and actor.
  • Given a high-severity incident is created, when severity meets configured threshold, then the system sends alerts to configured security contacts via email or integrations (e.g. incident management tools).
  • Given incidents are stored, when a compliance review is performed, then reviewers can export a report of incidents over a selected time range including type, status, and resolution notes.
  • Integrate with existing monitoring/alerting stack where possible.
  • Define severity levels and response playbooks outside of the application logic.
  • Ensure incident data does not expose unnecessary personal data.
Send to GitHub