CartFlow

Developer documentation

CartFlow CCOS API

REST endpoints for collaborative commerce — Living Carts, group funding, TrustPass reputation, and AI-assisted procurement. All responses use { ok: true, data: … } or { ok: false, error: … }.

Developer settingsBack to homepage

Base URL

Production: https://cart-flow.store

Local development: https://cart-flow.store (port 7900 per server config)

Authentication

Browser sessions use cookie-based auth via credentials: "include". Programmatic partners should use tenant API keys from Developer settings once enabled. Send Authorization: Bearer <api_key> for server-to-server calls.

Endpoints

POST/api/collaborative-carts

Create a Living Cart from the marketing API shape (group type, intent, payment rail).

POST https://cart-flow.store/api/collaborative-carts

{
  "groupType": "estate",
  "intent": "weekly_groceries",
  "deadline": "2026-07-15",
  "paymentRail": "mpesa",
  "trustPass": true
}

Response

{
  "ok": true,
  "data": {
    "id": "clx…",
    "title": "Estate Living Cart — weekly groceries",
    "shareCode": "a1b2c3d4e5",
    "isLivingCart": true,
    "livingCartCycle": "WEEKLY",
    "useCase": "estate:weekly_groceries",
    "expiresAt": null,
    "status": "DRAFT"
  }
}
  • Requires session authentication (cookie) or future API key.
  • When isLivingCart is true (default), deadline is ignored and expiresAt is null.
  • groupType maps to a default livingCartCycle (e.g. estate → WEEKLY, school → PER_TERM).
  • trustPass and paymentRail are accepted for partner integrations; TrustPass scoring applies at checkout.
GET/api/collaborative-carts

List your active Living Carts (isLivingCart=true, archivedAt=null).

GET https://cart-flow.store/api/collaborative-carts

Response

{
  "ok": true,
  "data": [
    {
      "id": "clx…",
      "title": "Estate Living Cart — weekly groceries",
      "isLivingCart": true,
      "livingCartCycle": "WEEKLY",
      "archivedAt": null,
      "_count": { "items": 12, "members": 8 }
    }
  ]
}
  • Returns carts where you are a member.
  • Archived carts are excluded.
POST/api/collaborative-carts/{cartId}/archive

Archive a Living Cart. Owners and approvers only.

POST https://cart-flow.store/api/collaborative-carts/:cartId/archive

Response

{
  "ok": true,
  "data": {
    "id": "clx…",
    "archivedAt": "2026-07-07T10:00:00.000Z"
  }
}
  • Sets archivedAt; cart no longer appears in active Living Cart lists.
  • Does not delete payment or order history.
POST/api/carts

Create a shared cart directly (lower-level than collaborative-carts).

POST https://cart-flow.store/api/carts

{
  "title": "Friday groceries",
  "splitRule": "PAY_OWN_ITEMS",
  "isLivingCart": true,
  "livingCartCycle": "WEEKLY"
}

Response

{
  "ok": true,
  "data": {
    "id": "clx…",
    "shareCode": "…",
    "isLivingCart": true,
    "livingCartCycle": "WEEKLY"
  }
}
  • Use collaborative-carts for partner integrations with groupType/intent.
  • Living Carts must not include expiresAt.
PATCH/api/carts/{cartId}

Update Living Cart metadata (title, cycle, budget, delivery).

PATCH https://cart-flow.store/api/carts/:cartId

{
  "livingCartCycle": "BIWEEKLY",
  "budgetLimit": 50000
}

Response

{
  "ok": true,
  "data": {
    "id": "clx…",
    "livingCartCycle": "BIWEEKLY",
    "budgetLimit": "50000.00"
  }
}
  • Only applies to non-archived Living Carts.
  • Owners and approvers only.
GET/api/ccos/ai/recommendations

Personalized procurement tips from purchase history.

GET https://cart-flow.store/api/ccos/ai/recommendations

Response

{
  "ok": true,
  "data": {
    "familySizeHint": "Based on your purchase history",
    "recommendations": [
      {
        "name": "maize flour 10kg",
        "usualQuantity": 4,
        "estimatedPrice": 450,
        "tip": "You often buy maize flour 10kg. Consider a group campaign for bulk savings."
      }
    ],
    "seasonalTip": "Maize flour prices often dip mid-month — good time for chama bulk buys."
  }
}
  • Powers the authenticated homepage AI section.
  • Falls back to static demo prompts when empty.

TrustPass

TrustPass scores appear on cart members and influence checkout safeguards. Query profiles via GET /api/trustpass/profiles and update onboarding via PATCH /api/trustpass/profiles/{id}. Collaborative cart creation accepts trustPass: true to enable risk-aware flows for new groups.

Webhooks & payments

M-Pesa and Kopo Kopo webhooks reconcile member shares automatically. Configure webhook endpoints in tenant payment settings. CartFlow emits reconciliation events suitable for ClariFi sync and partner webhooks — no payment secrets are required in API request bodies.

Quick start (curl)

Create a Living Cart

curl -X POST https://cart-flow.store/api/collaborative-carts \
  -H "Content-Type: application/json" \
  -H "Cookie: <session>" \
  -d '{
  "groupType": "estate",
  "intent": "weekly_groceries",
  "deadline": "2026-07-15",
  "paymentRail": "mpesa",
  "trustPass": true
}'