Cart & Orders API

Catalog: /apis/cart-api

Governs buyer shopping carts, checkout transformations, and order histories. Items added to a cart are dynamically hydrated with title and seller details at query time from Product & Seller services. During checkout, an immutable JSON snapshot is generated and frozen inside the order database column to protect receipt history integrity.

Endpoints Reference

Complete list of GraphQL mutations, queries, gRPC procedures, and HTTP routes for this module.

GraphQL Query

cart

Retrieves the hydrated active cart content for the buyer session.

🔒 JWT Auth BUYER

Request Syntax / Parameters

query { cart { id itemCount subtotal items { variantId quantity productTitle storeTitle unitPrice } } }

Expected JSON Response

{
  "data": {
    "cart": {
      "id": "427005c0-c1be-4cd7-aa2c-afe7265e4c3b",
      "itemCount": 1,
      "subtotal": 1199.99,
      "items": [
        {
          "variantId": "2eef484a-ea4b-4d5f-b762-401a55bd1f97",
          "quantity": 1,
          "productTitle": "iPhone 15 Pro Max",
          "storeTitle": "Cart Test Store",
          "unitPrice": 1199.99
        }
      ]
    }
  }
}

GraphQL Mutation

addToCart(variantId: ID!, quantity: Int!)

Adds a variant item to the cart. Increments quantity if already present.

🔒 JWT Auth BUYER

Request Syntax / Parameters

mutation { addToCart(variantId: "2eef484a-ea4b-4d5f-b762-401a55bd1f97", quantity: 1) { itemCount subtotal } }

Expected JSON Response

{ "data": { "addToCart": { "itemCount": 1, "subtotal": 1199.99 } } }

GraphQL Mutation

checkout(input: CheckoutInput!)

Transforms active cart contents into an Order, compiles frozen product snapshots, clears the cart, and publishes a wemall.order.created event to NATS.

🔒 JWT Auth BUYER

Request Syntax / Parameters

mutation { checkout(input: { shippingAddress: { fullName: "Tendai Moyo", addressLine1: "123 Samora Machel", city: "Harare", country: "ZW" }, currency: USD }) { id orderNumber total status } }

Expected JSON Response

{
  "data": {
    "checkout": {
      "id": "a35c3574-f16a-4770-84e6-3b7948e1b15d",
      "orderNumber": "WM-1780664885-cae5e5",
      "total": 1204.99,
      "status": "PENDING"
    }
  }
}

Database Tables & Data Models

Relational database schemas and custom payload models governing this service domain.

📂 cart_items (PostgreSQL)

Contains temporary items added by users. Un-enriched minimal table.

Field Name	Data Type	Description / Constraint
id	UUID (Primary Key)	Unique cart item identifier.
cart_id	UUID	Parent shopping cart reference.
variant_id	UUID	Product Variant identifier.
quantity	INTEGER	Requested count.

📂 order_items (PostgreSQL)

Contains frozen receipt lines containing immutable catalog snapshots.

Field Name	Data Type	Description / Constraint
id	UUID (Primary Key)	Unique order item receipt identifier.
order_id	UUID	Parent order reference.
variant_id	UUID	Purchased variant reference.
snapshot	JSONB	Immutable serialized snapshot record containing: variant options, seller logo, product title, and category codes at checkout time.