Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ALEJ4NDRO2025/urban-store/llms.txt
Use this file to discover all available pages before exploring further.
Urban Store ships a purpose-built analytics engine that records every meaningful shopper interaction as an immutable event in MongoDB. Those events feed four admin-only API views: a comprehensive dashboard with over a dozen KPIs, a step-by-step conversion funnel, an RFM customer segmentation model, and a real-time smart alerts system that flags anomalies before they hurt revenue.
Event Tracking System
Every event is persisted as an Event document in the analytics_events MongoDB collection, backed by the MongoEngine model defined in analytics/models.py. Each document carries the following fields:
| Field | Type | Description |
|---|
user_id | String | Email of the authenticated user, or null for guests |
session_id | String | Stable identifier from localStorage (required) |
event_type | String | The action being recorded (see table below) |
product_slug | String | Slug of the relevant product, if applicable |
product_name | String | Display name of the product |
price | String | Unit price at the time of the event |
metadata | Dict | Arbitrary extra data, e.g. { "quantity": 2 } |
source | String | Traffic source, e.g. google, instagram, direct |
idempotency_key | String | Unique key to deduplicate events in a 5-second window |
error_message | String | Error detail for error-type events |
created_at | DateTime | UTC timestamp, indexed for range queries |
POST /api/analytics/track/
Content-Type: application/json
{
"session_id": "abc-123",
"event_type": "add_to_cart",
"product_slug": "camiseta-oversize-negra",
"product_name": "Camiseta Oversize Negra",
"price": "79900",
"metadata": { "quantity": 1 },
"source": "instagram"
}
Tracked Event Types
| Event Type | When Fired |
|---|
page_view | User loads any page |
product_view | User opens a product detail page |
add_to_cart | User adds an item to the cart |
begin_checkout | User starts the checkout flow |
purchase | Order successfully paid via Stripe |
checkout_started | Checkout form is opened |
payment_info_entered | Payment details are submitted |
order_completed | Order confirmation page is viewed |
payment_error | Stripe payment fails |
checkout_error | Checkout form validation error |
payment_confirmation_error | Error confirming payment after submission |
address_error | Shipping address validation error |
whatsapp_cart_click | User clicked the WhatsApp buy button |
whatsapp_purchase | WhatsApp purchase confirmed |
Dashboard Stats
GET /api/analytics/dashboard-stats/?mode=total
Authorization: Bearer <admin_token>
mode query parameter accepts total (default) or unique. All metrics cover the last 7 days.
The response object contains the following metrics:
| Field | Description |
|---|
mode | The aggregation mode used — total or unique |
total_sales | Number of purchase events |
total_revenue | Sum of price × quantity across all purchases |
average_order_value | total_revenue / total_sales |
top_products | Top 5 products by units sold |
top_viewed_products | Top 5 products by views (unique sessions in unique mode) |
sales_by_day | Purchase count per calendar day |
abandonment_rate | % of begin_checkout identifiers that never reached purchase |
event_counts | Raw or unique counts for product_view, add_to_cart, begin_checkout, purchase |
conversion_rates | visit_to_cart, cart_to_checkout, checkout_to_purchase percentages |
checkout_started_count | Count of checkout_started events |
payment_info_entered_count | Count of payment_info_entered events |
order_completed_count | Count of order_completed events |
conversion_checkout_to_payment | Checkout-started → payment-entered conversion % |
conversion_payment_to_order | Payment-entered → order-completed conversion % |
error_counts | Counts for payment_error, checkout_error, payment_confirmation_error |
product_performance | Top 10 products with views, add-to-carts, purchases, and conversion rate |
events_timeline | Day-by-day breakdown of all key event types |
errors_timeline | Day-by-day error counts |
session_stats | Unique sessions, average events per session, sessions with purchase |
retention_metrics | Repurchase rate and recurrent customer counts over a 90-day window |
traffic_sources | Session counts grouped by source field |
whatsapp_sessions | Unique sessions that clicked the WhatsApp button |
whatsapp_purchases | Unique sessions with a whatsapp_purchase event |
whatsapp_sessions_list | Last 10 session IDs that clicked the WhatsApp button |
Conversion Funnel
GET /api/analytics/funnel/
Authorization: Bearer <admin_token>
page_view → product_view → add_to_cart → begin_checkout → purchase
| Parameter | Format | Description |
|---|
start | YYYY-MM-DD | Start of the date range (default: 30 days ago) |
end | YYYY-MM-DD | End of the date range (default: now) |
source | string | Filter to a specific traffic source, e.g. google |
{
"funnel": [
{ "step": "page_view", "count": 1842 },
{ "step": "product_view", "count": 940 },
{ "step": "add_to_cart", "count": 312 },
{ "step": "begin_checkout", "count": 98 },
{ "step": "purchase", "count": 67 }
],
"start_date": "2024-05-01T00:00:00",
"end_date": "2024-05-31T23:59:59"
}
RFM Segmentation
GET /api/analytics/rfm/
Authorization: Bearer <admin_token>
user_id on their purchase events are included.
Segment rules (applied in order):
| Segment | Spanish Label | Rule |
|---|
| VIP | VIP | Recency ≤ 7 days and frequency ≥ 2 and monetary ≥ 100,000 |
| Loyal | Leal | Recency ≤ 30 days and frequency ≥ 1 |
| At Risk | En riesgo | Recency ≤ 60 days |
| Lost | Perdido | Recency > 60 days |
{
"rfm": [
{
"visitor_id": "customer@example.com",
"recency": 3,
"frequency": 4,
"monetary": 318000,
"segmento": "VIP"
}
],
"start_date": "2024-03-02T00:00:00",
"end_date": "2024-05-31T23:59:59"
}
Smart Alerts
GET /api/analytics/alerts/
Authorization: Bearer <admin_token>
all_clear alert is returned.
| Alert Type | Severity | Trigger Condition |
|---|
high_abandonment | critical | Abandonment rate > 70% in the last 24 h, with ≥ 3 checkouts |
popular_no_conversion | warning | Product with > 10 unique views in 7 days and zero purchases |
payment_errors | critical | Any payment_error event in the last 1 hour |
carts_abandoned | warning | ≥ 5 cart sessions with no checkout start in the last 6 hours |
stuck_sessions | info | Sessions with > 15 events in 24 hours and no purchase |
type, message, severity, and timestamp.
mode=total vs mode=unique
The mode query parameter on the dashboard endpoint controls how event counts are aggregated.
| Mode | Behavior |
|---|
total | Counts every raw event occurrence — a user refreshing a product page 10 times adds 10 to product_view |
unique | Counts distinct session_id values — the same user counts once per step regardless of repetitions |
Use mode=unique when analyzing your conversion funnel. Unique-session counts eliminate noise from page refreshes and back-navigation, giving you a truer picture of how many distinct shoppers progressed through each stage.