Orders & Fulfillment Guide
Menu Path: Finance & Logistics > Orders
The Orders module is the central operational engine of the AVCI CMS ecosystem. It adapts dynamically based on your business model (Single-Vendor eCommerce vs. Multi-Vendor Marketplace) and the active user's permissions.
1. Persona & Profile Workflows
AVCI CMS strictly isolates user roles. Each profile interacts with orders and fulfillment through customized interfaces and security boundaries:
Profile 1: Platform Super Admin & Operations Manager (WORKSPACE_ADMIN / WORKSPACE_OWNER)
- Approval Queue: Orders requiring manual verification appear in
WAITINGstatus with a prominent "Approve" button that advances the status toPREPARING. - Active Cancellation / Return Alert Banner: If a customer submits a cancellation or return ticket via the Storefront, a red alert banner appears at the top of the order details:
"Active Customer Cancellation / Return Ticket Found! Review the ticket before dispatching courier packages."
- Marketplace Sub-Order Supervision: In Marketplace mode, admins inspect the master order and all individual sub-orders, verifying that each vendor fulfills their assigned items.
- Financial Ledger Oversight: In eCommerce mode, admins see store gross revenue, VAT, and shipping collected. In Marketplace mode, admins monitor commission splits and platform clearing.
Profile 2: Marketplace Vendor (WORKSPACE_MERCHANT)
- Isolated Sub-Order View: When a vendor logs in, they only see their assigned sub-order (
/orders/[subOrderId]). Vendors never have access to the master basket, other vendors' items, or global customer data. - Shipment Management (
OrderShipmentManager):- Automatic Barcode: Generates an integrated courier tracking number and printable shipping barcode with a single click.
- Manual Entry: If permitted by workspace settings, allows manual entry of carrier and tracking codes.
- Invoice Upload (
OrderInvoiceManager): Vendors upload the official PDF e-invoice (Sales Invoice, Return Invoice, or Cancel Invoice) and trigger automated email delivery to the customer. - RMA Return Approval: When a return request is submitted, the vendor reviews the request and generates a reverse-logistics courier return code.
Profile 3: Brand Owner (WORKSPACE_BRAND)
- GTIN / Master Catalog Oversight: Brands monitor which authorized merchants are selling their catalog items.
- Shipping Precedence: If a brand sets up custom courier contracts, the basket engine automatically gives precedence to the brand's shipping rules over the merchant's rules.
Profile 4: Finance Specialist (WORKSPACE_FINANCE)
- Payout Reconciliation: Finance specialists monitor seller payout statuses (
PENDING,READY,PAID,CANCELED). - Withholding & Commission Deductions: Inspects withholding taxes (stopaj) and net payouts calculated per line item.
- Master Wallet Overview: Tracks platform transaction volume and automated clearing cycles (
/finance).
Profile 5: End User / Customer (USER - Storefront)
- Zero Management Panel Access: Customers never have access to the AVCI CMS management console.
- Storefront Account Portal: Customers track order statuses, view courier tracking links, and download event ticket PDFs / QR passes directly in the Storefront customer account.
- Cancellation & Return Process (RMA via Tickets):
- The customer selects an order item and clicks "Cancel Order" or "Request Return" on the Storefront.
- The system automatically creates a support ticket in the
ticketmodule with categoryCANCELLATIONorRETURN. - The management panel displays the urgent alert banner, enabling the merchant or admin to approve the return and issue the reverse courier barcode.
Profile 6: Storefront Integrator (DEVELOPER)
- Integrators use
@avci/sdkor the Python SDK to interact with public endpoints (/v1/basketand/v1/order). - Management endpoints (
/management/*) are strictly excluded from SDKs and are reserved solely for the management frontend application.
2. Order Fulfillment Workflow
Step 1: Order Intake & Verification
- Order arrives in
WAITING(if review required) orPREPARINGstatus. - Operator or merchant reviews the Summary Card, customer notes, and the Order Health Card for automated diagnostic flags (e.g. payment mismatches or address discrepancies).
Step 2: Attendees & Ticketed Items (Events & Routes)
- If the order contains ticketed items, the Attendees Card lists the full name, email, phone, and unique QR hash for every registered ticket holder.
- Route tickets register participants for all sequenced events within the tour automatically.
Step 3: Courier Shipment Dispatch
- Open the Shipment Management card.
- Click Generate Shipment Code to create an automated barcode with the selected courier (e.g. Aras, Yurtiçi, MNG).
- Print the courier shipping label and hand the package to the carrier.
- The order status automatically updates to
ON_SHIPMENT, and the customer receives an automated SMS and email tracking notification.
Step 4: Invoice Upload & Customer Delivery
- Open the Invoice Management card.
- Select the invoice type (Sales Invoice, Return Invoice, or Cancel Invoice).
- Upload the PDF file and click Send to Customer to deliver the invoice via transactional email.
Step 5: Handling Cancellations & RMA Returns
- When a customer initiates a return, the red Cancellation Alert Banner appears on the order.
- Clicking View Ticket opens the associated support ticket in
/tickets/[id]. - If approved, the merchant generates a Return Courier Code in the Shipment Manager so the customer can ship the package back free of charge.
- Once goods are received, the operator completes the return, automatically canceling the seller payout in the financial ledger.