Skip to main content

Data Models Reference

Related docs: API Design · Payment Architecture · Order Lifecycle

User​

The User entity represents all platform actors. It stores basic profile information, authentication metadata, and role assignments.

  • Key Attributes: Email, Name, Phone, Role (Buyer, Shop Owner, Delivery Agent, Admin).
  • Core Relations: Linked to Orders, Shops (via ownership), Delivery Agent Profiles, and Notifications.

Shop​

A Shop represents a vendor's presence on the marketplace.

  • Key Attributes: Name, Slug (URL), Verification Status, Branding (logo/cover).
  • Core Relations: Linked to Products, Order Items, and Payout Methods.

2. Order and Transaction Models​

Order​

Tracks the overall customer journey from basket to delivery.

  • Key Attributes: Order Number, Status (Pending, Confirmed, Shipped, Delivered), Totals (Subtotal, Tax, Delivery), and Delivery Contact Info.
  • Core Relations: Parent to Order Items and Inbound Payments.

Order Item​

Represents individual products within an order, used for granular settlement tracking.

  • Key Attributes: Quantity, Price, Platform Fee, and Settlement Status (Held, Releasable, Paid Out).
  • Core Relations: Linked to the parent Order, the Product, and the selling Shop.

3. Payment and Settlement Models​

Inbound Payment​

Records each attempt made by a customer to pay for an order.

  • Key Attributes: Gateway (PawaPay, Flutterwave), Reference ID, Status (Captured, Failed), and Idempotency Key.

Vendor Payout​

Represents the disbursement of funds to a vendor after successful delivery.

  • Key Attributes: Amount, Payout Status (Processing, Completed), and Gateway Reference.

Webhook Event​

Ensures reliable and idempotent processing of incoming notifications from payment providers by logging every event received.

Shop Payout Method​

Stores the vendor's preferred financial destination for their earnings, such as a Mobile Money wallet or a bank account.

4. Delivery Models​

Delivery Agent​

The DeliveryAgent entity represents independent contractors or courier companies responsible for final-mile logistics.

  • Key Attributes: Agent Type (Individual/Company), Status (Active, Pending), and Real-time Availability.
  • Core Relations: Linked to a User profile and multiple Delivery Confirmations.

Delivery Confirmation​

Ensures secure order hand-off through a dual-party verification system.

  • Key Attributes: Confirmation PIN, Verification Photo, and Completion Timestamp.
  • Core Relations: Linked to a specific Order and the assigned Delivery Agent.

4. Key Relationships​

5. Enum Quick Reference​

EnumValues
UserRoleBUYER · SHOP_OWNER · DELIVERY_AGENT · PLATFORM_ADMIN
OrderStatusPENDING · CONFIRMED · PROCESSING · SHIPPED · DELIVERED · CANCELLED · REFUNDED
PaymentStatusPENDING · PAID · FAILED · REFUNDED
SettlementStatusHELD · RELEASABLE · PAID_OUT
InboundPaymentStatusPENDING · CAPTURED · FAILED · REFUNDED
PaymentGatewayPAWAPAY · FLUTTERWAVE · MOCK
PayoutStatusPENDING · PROCESSING · COMPLETED · FAILED