Docs
Dashboard

Commerce Graph

The Commerce Graph is GullyPay's real-time graph of the commerce network. It records nodes (users, merchants, products) and edges (the relationships between them — purchases, referrals, and other connections) and powers recommendations, referral attribution, and network insights.

Every time a purchase is recorded, the graph links the buyer to the merchant and to the purchased product. Those connections accumulate into a network you can query for insights and recommendations.

Graph model

A node has a nodeType (user, merchant, product), an entityId (the id of the underlying record), and a label. An edge connects a sourceId node to a targetId node with an edgeType (e.g. purchased, bought_from) and a weight.

Authentication

All /graph endpoints require a valid JWT access token.

Authorization header
Authorization: Bearer <access_token>

Endpoints

GET/graph/merchants/:merchantId/insightsRead-only network summary for a merchant
GET/graph/recommendationsGraph-powered recommendations for the authenticated user
GET/graph/nodes/:typeList graph nodes of a given type
GET/graph/nodes/:id/edgesList outbound edges from a node
POST/graph/nodesCreate a graph node
POST/graph/edgesCreate an edge between two nodes
POST/graph/purchaseRecord a purchase (links user → product and user → merchant)

GET /graph/merchants/:merchantId/insights

Returns an aggregated, read-only summary of the commerce graph for a merchant. All values are computed live from the graph tables — an empty graph returns real zeros and empty lists.

Response
{
"merchantNodeId": "b2c3d4e5-...",
"inGraph": true,
"totalNodes": 128,
"totalEdges": 342,
"nodesByType": [
  { "type": "user", "count": 84 },
  { "type": "merchant", "count": 12 },
  { "type": "product", "count": 32 }
],
"edgesByType": [
  { "type": "purchased", "count": 171 },
  { "type": "bought_from", "count": 171 }
],
"connectedCustomers": 41,
"purchaseEvents": 171,
"recentActivity": [
  {
    "id": "e1f2a3b4-...",
    "edgeType": "bought_from",
    "weight": 1,
    "sourceId": "a1b2c3d4-...",
    "sourceLabel": "user_a1b2c3d4",
    "sourceType": "user",
    "createdAt": "2026-07-18T12:01:00Z"
  }
]
}
FieldTypeDescription
merchantNodeIdstring | nullThe merchant's node id in the graph, or null if not yet present
inGraphbooleanWhether the merchant has appeared in the graph yet
totalNodesnumberTotal node count across the whole graph
totalEdgesnumberTotal edge count across the whole graph
nodesByTypearrayNode counts grouped by type
edgesByTypearrayEdge counts grouped by type
connectedCustomersnumberDistinct customers with a bought_from edge to this merchant
purchaseEventsnumberCount of bought_from edges to this merchant
recentActivityarrayUp to 10 most recent inbound edges, with the source node's label and type

GET /graph/recommendations

Returns graph-powered recommendation nodes for the authenticated user, derived from the user's existing edges.

Response
[
{
  "id": "c3d4e5f6-...",
  "nodeType": "product",
  "entityId": "p1q2r3s4-...",
  "label": "product_p1q2r3s4",
  "metadata": {},
  "createdAt": "2026-07-18T11:40:00Z"
}
]
Early-network behavior

Recommendations are seeded from the user's own graph edges. Until an account has transacted across the network, this endpoint returns an empty array. As purchase activity accumulates, relevant merchants and products surface here.

GET /graph/nodes/:type

List all nodes of a given nodeType (user, merchant, or product).

Request
curl https://gullypay.xyz/api/graph/nodes/merchant \
-H "Authorization: Bearer <access_token>"

POST /graph/purchase

Records a purchase in the graph. This ensures nodes exist for the user, merchant, and product, then creates a purchased edge (user → product) and a bought_from edge (user → merchant).

Request Body
{
"userId": "a1b2c3d4-...",
"merchantId": "b2c3d4e5-...",
"productId": "p1q2r3s4-..."
}
Response
{ "recorded": true }

POST /graph/nodes

Request Body
{
"nodeType": "product",
"entityId": "p1q2r3s4-...",
"label": "Wireless Headphones",
"metadata": { "category": "audio" }
}

POST /graph/edges

Request Body
{
"sourceId": "a1b2c3d4-...",
"targetId": "p1q2r3s4-...",
"edgeType": "purchased",
"weight": 1
}

Merchant Dashboard

The Commerce Network page in the merchant dashboard consumes GET /graph/merchants/:merchantId/insights and GET /graph/recommendations to display network stats (node/edge counts by type), connected customers, purchase events, recent network activity, and graph-powered recommendations — with real loading and empty states.

Next Steps